rails-engine-testing

Rails Engine Testing

Use this skill when the task is to create or improve test coverage for a Rails engine.

Quick Reference

| Spec Type | Purpose | |-----------|---------|| | Request | Proves mounted endpoints work; exercises real routing and controller | | Routing | Verifies engine route expectations and mount behavior | | Generator | Covers install commands, copied files, idempotency | | Config | Verifies engine respects host configuration overrides | | Reload-safety | Regression tests for decorators, patches, and to_prepare hooks |

HARD-GATE

EVERY engine MUST have a dummy app for testing.

Generate one if it doesn't exist:

cd my_engine && bundle exec rails plugin new . --dummy-path=spec/dummy --skip-git

Validate the dummy app boots before proceeding:

cd spec/dummy && bundle exec rails runner "puts 'Boot OK'"

If this fails, check the engine's engine.rb initializer order and ensure the engine is correctly mounted in spec/dummy/config/routes.rb before writing any specs.

Testing Order

1. Identify the engine type and public behaviors.
2. Decide which behaviors need unit tests versus dummy-app integration tests.
3. Add the smallest integration test that proves mounting and boot work. Verify it passes before continuing — if it fails, check engine.rb initializer order and mount configuration rather than adding more specs on top of a broken foundation.
4. Add request, routing, configuration, and generator coverage as needed.
5. Add regression tests for coupling or reload bugs before refactoring.
6. Verify: dummy app exercises real host integration; routes tested through engine namespace; configurable seams covered with at least one non-default case; generators safe to run twice.

Minimum Baseline

For a non-trivial engine, aim for:

• one dummy-app boot or integration spec
• one request or routing spec for mounted endpoints
• one configuration spec for host customization
• unit tests for public services or POROs

If generators exist, add generator specs. If decorators or reload hooks exist, add reload-focused coverage.

Minimal request spec to prove the engine mounts:

# spec/requests/my_engine/root_spec.rb
require 'rails_helper'

RSpec.describe 'MyEngine mount', type: :request do
  it 'returns ok for the engine root' do
    get my_engine.root_path
    expect(response).to have_http_status(:ok)
  end
end

Configuration spec (engine respects host config):

# spec/my_engine/configuration_spec.rb
RSpec.describe MyEngine::Configuration do
  around do |example|
    original = MyEngine.config.widget_count
    MyEngine.config.widget_count = 3
    example.run
    MyEngine.config.widget_count = original
  end

  it 'uses configured value' do
    expect(MyEngine.config.widget_count).to eq(3)
  end
end

For generator and reload-safety spec examples, see assets/examples.md.

Pitfalls

Pitfall	What to do
Skipping reload-safety tests	Add regression coverage for decorators and patches in development
Tests pass only with specific Rails version	Run a version matrix; pin nothing unless required
Request specs use stubs instead of real wiring	Mount the engine in dummy and call through it
Install generators without file assertions	Assert copied files and idempotency in generator specs

Integration

Skill	When to chain
rails-engine-author	When structuring the engine for testability or adding configuration seams
rails-engine-reviewer	When validating test coverage adequacy or identifying gaps
rspec-best-practices	When improving spec structure, matchers, or shared examples

Assets

• assets/dummy_app_instructions.md
• assets/examples.md