thoughtbot/shoulda-matchers · error · TestFrameworkNotConfigured

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

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.

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

• '# ' is not registered

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

Appendix: 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)