thoughtbot/shoulda-matchers · error · TestFrameworkNotConfigured

You need to set a test framework. Please add the following t

Error message

You need to set a test framework. Please add the following to your
test helper:

Shoulda::Matchers.configure do |config|
  config.integrate do |with|
    # Choose one:
    with.test_framework :rspec
    with.test_framework :minitest    # or, :minitest_5
    with.test_framework :minitest_4
    with.test_framework :test_unit
  end
end

What it means

TestFrameworkNotConfigured is raised by Shoulda::Matchers::Integrations::TestFrameworks::MissingTestFramework#validate! (lib/shoulda/matchers/integrations/test_frameworks/missing_test_framework.rb:9-24). MissingTestFramework is a placeholder object seeded as the default when an Integrations::Configuration is created (configuration.rb:16 calls test_framework :missing_test_framework); it survives only if your configure block never calls with.test_framework, and its validate! exists solely to abort with these instructions. Since shoulda-matchers 3.0 the gem no longer auto-detects your test framework — you must declare it in a Shoulda::Matchers.configure block in your test helper — and this error means that declaration is missing or the block that contains it never executed.

Source

Thrown at lib/shoulda/matchers/integrations/test_frameworks/missing_test_framework.rb:10

module Shoulda
  module Matchers
    module Integrations
      module TestFrameworks
        # @private
        class MissingTestFramework
          Integrations.register_test_framework(self, :missing_test_framework)

          def validate!
            raise TestFrameworkNotConfigured, <<-EOT
You need to set a test framework. Please add the following to your
test helper:

Shoulda::Matchers.configure do |config|
  config.integrate do |with|
    # Choose one:
    with.test_framework :rspec
    with.test_framework :minitest    # or, :minitest_5
    with.test_framework :minitest_4
    with.test_framework :test_unit
  end
end
            EOT
          end

          def include(*modules, **options)
          end

View on GitHub (pinned to 79cdfbc326)

Solutions

1. Add the configure block shown in the error message to the helper every test loads — spec_helper.rb (or rails_helper.rb) for RSpec, test_helper.rb for minitest/Test::Unit — choosing exactly one with.test_framework line.
2. Verify the file containing the block is actually required on every run: for RSpec+Rails it belongs in rails_helper.rb after require 'rspec/rails'; a block in an unloaded support file is the same as no block.
3. If a block already exists, check it for the exact spelling Shoulda::Matchers.configure (plural Matchers) and confirm it contains a with.test_framework line — with.library alone is not enough, and Shoulda::Matcher.configure fails silently as an undefined method.
4. After a major-version bump of shoulda-matchers, re-read the README's configuration section and diff it against your helper; 2.x configured nothing and 3.0+ requires the block.

Example fix

# before — spec_helper.rb
require 'shoulda/matchers'
# no configure block: MissingTestFramework#validate! raises TestFrameworkNotConfigured

# after
require 'shoulda/matchers'

Shoulda::Matchers.configure do |config|
  config.integrate do |with|
    with.test_framework :rspec
    with.library :rails
  end
end

require 'shoulda/matchers'

framework = if defined?(RSpec)
              :rspec
            elsif defined?(Minitest::VERSION)
              Gem::Version.new(Minitest::VERSION) >= Gem::Version.new('5.0') ? :minitest_5 : :minitest_4
            end

abort 'No supported test framework loaded before shoulda-matchers' unless framework

Shoulda::Matchers.configure do |config|
  config.integrate do |with|
    with.test_framework framework
    with.library :rails
  end
end

raise 'shoulda-matchers configure block never ran' if Shoulda::Matchers.integrations.nil?

begin
  require_relative 'support/shoulda_setup'
rescue StandardError => e
  if e.class.name.end_with?('TestFrameworkNotConfigured')
    abort "shoulda-matchers is not configured for a test framework:\n#{e.message}"
  end
  raise
end

When it happens

Trigger: Running the suite with shoulda-matchers required but no Shoulda::Matchers.configure block anywhere that actually executed. Writing `config.integrate { |with| with.library :rails }` with no with.test_framework line, so the seeded MissingTestFramework is still the framework being integrated. Putting the block in a helper that only some runs load (block in rails_helper.rb while the failing spec loads only spec_helper.rb, or in a support file that is never required). The gem upgrading path: shoulda-matchers 2.x needed no configure block, so a bundle update to 3.0+ makes every suite that never had one fail with this message.

Common situations: Upgrading shoulda-matchers from 2.x to 3.0+ without adding the (now mandatory) configure block — the most common hit; adding the gem to a new Rails app without pasting the initializer snippet into spec_helper/rails_helper/test_helper; a typo in the block (Shoulda::Matcher.configure, missing s) leaving a defined-but-never-run method; the block placed after or outside the files the test runner requires; CI using a different helper than local runs.

Related errors

• '#{name}' is not registered

AI-assisted analysis of thoughtbot/shoulda-matchers@79cdfbc326 (2026-08-23). Data as JSON: /api/errors/b3a75fe99b57ca21. Report an issue: GitHub.