Skip to content

testing.md

Latest commit

 

History

History
133 lines (91 loc) · 4.38 KB

testing.md

File metadata and controls

133 lines (91 loc) · 4.38 KB
Raw

Testing

This chapter describes the testing setup shipped with the Folio Rails Engine and how to write and run tests for your application.

Test Framework & Tools

Folio uses the default Minitest framework that ships with Rails, extended with several helpful gems:

Gem Purpose
capybara System/feature tests (browser automation)
capybara-minitest Integrates Capybara with Minitest assertions
factory_bot Factories for test data
vcr + webmock Record and stub external HTTP requests

You can find the core setup in test/test_helper_base.rb.

Test Helpers & Base Classes

The engine defines several base classes that you can inherit from:

Class Inherits Use case
ActiveSupport::TestCase Minitest unit test Model/unit tests (includes FactoryBot)
Cell::TestCase Tests for legacy Trailblazer Cells
ActionDispatch::IntegrationTest Controller & request tests (Devise helpers included)
Folio::CapybaraTest IntegrationTest Full-stack browser tests with Capybara
Folio::ComponentTest ViewComponent::TestCase Tests for ViewComponents
Folio::BaseControllerTest ActionDispatch::IntegrationTest Adds site and user handling
Folio::Console::BaseControllerTest Folio::BaseControllerTest Creates and signs in a superadmin user

Each base class automatically:

  • Resets Folio::Current context (site/user)
  • Includes FactoryBot::Syntax::Methods
  • Provides helpers from test/support/

Factories

Factories live in test/factories.rb and are loaded via FactoryBot. When you generate new models, remember to add corresponding factories.

factory :my_application_list, class: "MyApplication::List" do
  title { "hello" }
  published { true }
end

Running Tests

rails test           # run all tests

Parallel testing is enabled by default (parallelize in test_helper_base.rb). Suites with 100 or fewer loaded test methods run serially; larger suites use at most 8 workers, capped by the detected processor count.

Change the automatic cap or threshold when needed:

TEST_MAX_WORKERS=6 bundle exec rails test
TEST_MAX_WORKERS=0 bundle exec rails test
TEST_PARALLELIZATION_THRESHOLD=200 bundle exec rails test
TEST_PARALLELIZATION_THRESHOLD=0 bundle exec rails test

TEST_MAX_WORKERS only limits automatic parallelization; set it to 0 to remove the cap and use Rails' default processor-count handling. TEST_PARALLELIZATION_THRESHOLD=0 uses Rails' default test-count threshold. PARALLEL_WORKERS remains Rails' exact explicit override: it can exceed the automatic cap and bypasses the test-count threshold.

To run tests sequentially (useful for debugging):

PARALLEL_WORKERS=1 bundle exec rails test

Troubleshooting

Tests Hang Indefinitely in Parallel Mode

If tests hang during parallel execution with errors like:

DRb::DRbConnError: drbunix:/tmp/druby12345.0 - No such file or directory

This is usually caused by stale database connections from a previous interrupted test run. The "idle in transaction" connections hold locks that block parallel test workers from setting up their test databases.

Solution: Terminate stale connections before running tests:

psql -c "SELECT pg_terminate_backend(pid) FROM pg_stat_activity WHERE datname LIKE 'your_app_test%' AND state = 'idle in transaction';" your_app_test

Replace your_app_test with your actual test database name (e.g., folio_test).

Prevention: Always allow test runs to complete gracefully. If you must interrupt (Ctrl+C), the cleanup should handle connections, but occasionally stale connections remain.

Best Practices

  • Use factories instead of fixtures for clearer intent.
  • Use the provided base classes so Folio::Current is managed for you.
  • Record external API calls with VCR to keep tests deterministic.
  • VCR filters FOLIO_AI_OPENAI_API_KEY, FOLIO_AI_ANTHROPIC_API_KEY, OPENAI_API_KEY, and ANTHROPIC_API_KEY automatically and does not persist failed OpenAI/Anthropic HTTP responses.
  • Prefer Component tests for ViewComponent logic and rendering.

Navigation

This testing overview will be updated as the documentation evolves.