{"record":{"id":"b3a75fe99b57ca21","repo":"thoughtbot/shoulda-matchers","slug":"you-need-to-set-a-test-framework-please-add-the-f","errorCode":null,"errorMessage":"You need to set a test framework. Please add the following to your\ntest helper:\n\nShoulda::Matchers.configure do |config|\n  config.integrate do |with|\n    # Choose one:\n    with.test_framework :rspec\n    with.test_framework :minitest    # or, :minitest_5\n    with.test_framework :minitest_4\n    with.test_framework :test_unit\n  end\nend\n","messagePattern":"You need to set a test framework\\. Please add the following to your\ntest helper:\n\nShoulda::Matchers\\.configure do \\|config\\|\n  config\\.integrate do \\|with\\|\n    # Choose one:\n    with\\.test_framework :rspec\n    with\\.test_framework :minitest    # or, :minitest_5\n    with\\.test_framework :minitest_4\n    with\\.test_framework :test_unit\n  end\nend\n","errorType":"exception","errorClass":"TestFrameworkNotConfigured","httpStatus":null,"severity":"error","filePath":"lib/shoulda/matchers/integrations/test_frameworks/missing_test_framework.rb","lineNumber":10,"sourceCode":"module Shoulda\n  module Matchers\n    module Integrations\n      module TestFrameworks\n        # @private\n        class MissingTestFramework\n          Integrations.register_test_framework(self, :missing_test_framework)\n\n          def validate!\n            raise TestFrameworkNotConfigured, <<-EOT\nYou need to set a test framework. Please add the following to your\ntest helper:\n\nShoulda::Matchers.configure do |config|\n  config.integrate do |with|\n    # Choose one:\n    with.test_framework :rspec\n    with.test_framework :minitest    # or, :minitest_5\n    with.test_framework :minitest_4\n    with.test_framework :test_unit\n  end\nend\n            EOT\n          end\n\n          def include(*modules, **options)\n          end\n","sourceCodeStart":1,"sourceCodeEnd":28,"githubUrl":"https://github.com/thoughtbot/shoulda-matchers/blob/79cdfbc326e97c9b43991b644434ca53c1f62c4c/lib/shoulda/matchers/integrations/test_frameworks/missing_test_framework.rb#L1-L28","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["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.","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.","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.","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."],"exampleFix":"# before — spec_helper.rb\nrequire 'shoulda/matchers'\n# no configure block: MissingTestFramework#validate! raises TestFrameworkNotConfigured\n\n# after\nrequire 'shoulda/matchers'\n\nShoulda::Matchers.configure do |config|\n  config.integrate do |with|\n    with.test_framework :rspec\n    with.library :rails\n  end\nend","handlingStrategy":"validation","validationCode":"require 'shoulda/matchers'\n\nframework = if defined?(RSpec)\n              :rspec\n            elsif defined?(Minitest::VERSION)\n              Gem::Version.new(Minitest::VERSION) >= Gem::Version.new('5.0') ? :minitest_5 : :minitest_4\n            end\n\nabort 'No supported test framework loaded before shoulda-matchers' unless framework\n\nShoulda::Matchers.configure do |config|\n  config.integrate do |with|\n    with.test_framework framework\n    with.library :rails\n  end\nend\n\nraise 'shoulda-matchers configure block never ran' if Shoulda::Matchers.integrations.nil?","typeGuard":null,"tryCatchPattern":"begin\n  require_relative 'support/shoulda_setup'\nrescue StandardError => e\n  if e.class.name.end_with?('TestFrameworkNotConfigured')\n    abort \"shoulda-matchers is not configured for a test framework:\\n#{e.message}\"\n  end\n  raise\nend","preventionTips":["Put the Shoulda::Matchers.configure block in the helper file every test loads (spec_helper.rb/rails_helper.rb for RSpec, test_helper.rb for minitest) — not in a support file only some suites require.","Fail fast at boot: after loading helpers, assert Shoulda::Matchers.integrations is non-nil (it stays nil until config.integrate runs), so a silently skipped block kills CI instead of the first spec.","After any shoulda-matchers major-version bump, re-read its configuration README; 2.x required no configure block and 3.0+ makes it mandatory.","Spell it Shoulda::Matchers.configure (plural Matchers) and always include a with.test_framework line — with.library alone leaves the missing-framework placeholder in place.","Detect the framework programmatically (defined?(RSpec) ? :rspec : :minitest_5) instead of hardcoding, so the block cannot drift from the frameworks the app actually loads."],"tags":["ruby","shoulda-matchers","rspec","minitest","test-unit","configuration","test-setup"],"backgroundTag":"missing-configuration","analyzedSha":"79cdfbc326e97c9b43991b644434ca53c1f62c4c","analyzedAt":"2026-08-23T09:43:24.200Z","schemaVersion":2},"datasetVersion":"2026-08-23T13:39:53.451Z"}