Overseer testing-control Rails helper

An optional Rails adapter for Overseer testing protocol v3. The protocol owns schemas, wire conventions and HTTP conformance. This gem owns Rails routing, safe JSON responses, correlation and bounded memory stores. It works with frontend tests, curl and CI without Overseer Studio.

For a checkout before a published release, the repository includes an exact protocol package snapshot under vendor/. Applications should pin reviewed package snapshots or released versions in their test-only bundle:

group :test do
  gem 'overseer-testing-protocol', path: 'vendor/gems/overseer-testing-protocol', require: false
  gem 'overseer-testing-control-rails', path: 'vendor/gems/overseer-testing-control-rails',
      require: 'overseer/testing_control/rails'
end

Mount Overseer::TestingControl::Rails::Engine at /v1/testing only in test. Configure it in a test-only initializer:

Overseer::TestingControl::Rails.configure do |config|
  config.identity(application: 'my-api', source: -> { ENV.fetch('TEST_SOURCE') },
                  environment: -> { ENV.fetch('TEST_RUNTIME_ID') })
  config.reset(strategy: 'runtime-restart')
  config.register_state(id: 'open-item', version: '1', title: 'Open synthetic item',
                        idempotency: 'required', input_schema: OPEN_ITEM_INPUT,
                        output_schema: OPEN_ITEM_OUTPUT, handler: Testing::OpenItem.method(:call))
end

The adapter fails closed unless Rails is in test, OVERSEER_TESTING_CONTROL_ENABLED=true, and configured identity providers are valid. The host must additionally verify its isolation, database identity, synthetic data and credential policy. The helper cannot establish network containment or safely identify a database on its own.

Register probes with input/output schemas and a read-only handler callable receiving (input, context). Register sinks with effect kinds, outcomes, query_input_schema, record_schema and a query_matcher receiving (payload, input). A matcher must return true for each record to retain. Non-empty query input without a matcher is rejected rather than ignored. Matchers and probe handlers must have no side effects.

At a product-owned fake boundary, call Overseer::TestingControl::Rails.capture_effect(capability:, version:, effect_kind:, summary:, payload:, outcome:). Supply only sanitized fields allowed by the registered schema. The helper records the current public request's run and correlation; step IDs are optional. Records are partitioned by run and queries do not consume them. Storage is bounded and fails on exhaustion. It does not silently discard records.

Internal spies are product-owned bounded event stores exposed through probes. There is no arbitrary method interception, model inspection or /spies route. Product semantics and safe fields remain in the application.

This implementation supports one process, with synchronous request effects. Its middleware serializes active public and control requests so reset cannot race them. Independent test suites need independent runtimes. Worker processes, streaming effects and automatic Active Job/Sidekiq correlation propagation are not implemented. Do not advertise worker completion using a pre-enqueue record.

For an in-process reset, config.reset(strategy: 'in-process', handler: ...) requires a handler returning exactly true after all product state is reset. False, nil, a failure object or an exception cannot report success; helper stores are retained on failure. A successful reset clears observations and idempotency. The product must own file, job, cache, database and external fake cleanup.

bundle install
bundle exec rake test
gem build overseer-testing-control-rails.gemspec

Run the protocol package's HTTP conformance command against a disposable host application to check the complete adapter. The package has no Studio, container orchestration or product persistence dependency.

Made with ❤️ by olistik