Kaisoku is a research-backed Ruby test feedback engine for safe regression test selection. It records dynamic dependencies per test entity, selects the tests affected by a change, and falls back to a full run when it cannot preserve safety.

Install the gem and add it to your application's Gemfile by executing:

bundle add kaisoku

If bundler is not being used to manage dependencies, install the gem by executing:

gem install kaisoku

Build the initial dependency map:

kaisoku map build

Run tests affected by changed files:

kaisoku run app/models/user.rb

Run all tests or previous failures:

kaisoku run --all
kaisoku run --failed

Start watch mode:

kaisoku watch app lib spec

Inspect map health and preload state:

kaisoku doctor --preload

Export and import dependency maps for CI or cache reuse:

kaisoku map export > .kaisoku/map.json
kaisoku map import .kaisoku/map.json

Evaluate selection quality:

kaisoku eval --total 100 --selected 12 --ci
kaisoku eval --commits 20 --json-report .kaisoku/eval-report.json

Unsafe predictive mode is explicit:

kaisoku run --predictive

• RSpec
• minitest
• test-unit
• Cucumber

Select an adapter with --adapter:

kaisoku run lib/user.rb --adapter minitest

• Dynamic file-level dependency maps stored in SQLite
• Smart Ruby checksums that ignore comments while preserving semantic magic comments
• Safe fallback rules for unknown files, boot-impact files, Ruby/Gemfile changes, and stale maps
• Fork-based parallel scheduling and failure-first prioritization
• Watch mode, daemon RPC, console/TUI/JSON/JUnit reporters, and map export/import
• Hot-file diagnostics and method-level HyRTS policy
• Evaluation commands for selection metrics, JSON reports, CI history, commit replay, and mutation seeding
• Preload integrity tracking, Rails-specific hooks, and inline snapshot matcher support

After checking out the repo, run:

bundle install

Run the test suite:

bundle exec rake

Run the executable from the checkout:

bundle exec ruby -Ilib exe/kaisoku --help

Build the gem locally:

gem build kaisoku.gemspec

Bug reports and pull requests are welcome on GitHub at https://github.com/ydah/kaisoku.

The gem is available as open source under the terms of the MIT License.