padded_cell 0.1.0

data/README.md

@@ -0,0 +1,184 @@
+# padded_cell
+
+Your tests aren't crazy. They just need their own room.
+
+padded_cell is a drop-in runner for Minitest and Rails test suites. Nothing in
+your tests changes; padded_cell replaces the thing that runs them:
+
+- **every test in its own forked cell**: a test that segfaults, calls `exit`,
+  hangs, monkey patches `Time` or leaves a thread behind takes down its cell,
+  not the run, and not the next test (Rails suites with fixtures default to
+  sharing a worker instead, see [Isolation](#isolation));
+- **workers fed whole classes**, slowest first from the timings of the
+  previous run, so per-class setup such as fixtures happens once; idle
+  workers split the remaining big classes;
+- **static discovery** with Prism: `file:line`, `--list` and CI sharding work
+  without loading a single test file;
+- Minitest's own reporters and plugins, plus JUnit XML and JSON lines.
+
+Discovery and scheduling are Rust, in a native extension: Prism parses the
+test files on every core, and a deterministic scheduler orders the run.
+
+```console
+$ bundle exec padded_cell
+Run options: --seed 33512 --isolation test
+
+# Running:
+
+.....E.......................................
+
+Finished in 2.083220s, 21.6013 runs/s, 233.2927 assertions/s.
+
+  1) Error:
+PaymentTest#test_refund:
+PaddedCell::CellCrashed: cell killed by SIGABRT
+    test/models/payment_test.rb:41:in 'PaymentTest#test_refund'
+
+45 runs, 486 assertions, 0 failures, 1 errors, 0 skips
+```
+
+One test segfaulted a C extension (Ruby aborts on a segfault) and took its cell
+down. The other 44 never noticed.
+
+## Installation
+
+Requires CRuby 4.0 or newer and Minitest 6, on Linux, macOS or FreeBSD.
+padded_cell is built on `fork`: Windows, JRuby and TruffleRuby are not
+supported.
+
+```ruby
+group :test do
+  gem "padded_cell"
+end
+```
+
+Precompiled gems ship for Linux (x86_64 and aarch64; glibc 2.34+ such as
+Debian 13, Ubuntu 26.04, RHEL 10, Fedora, Arch or Omarchy, plus musl for
+Alpine), macOS 13+ (arm64, x86_64) and FreeBSD 15.1 (amd64): no Rust, no
+compiler, nothing to build. Anything else (another CPU, an older glibc) gets
+the source gem, which compiles the extension at install and needs Rust 1.99+.
+padded_cell does not load without its extension.
+
+## Usage
+
+```console
+$ padded_cell                              # test/**/*_test.rb, minus system, dummy and fixtures
+$ padded_cell test/models                  # a directory
+$ padded_cell test/models/user_test.rb:12  # the test spanning line 12
+$ padded_cell user_test.rb:12-30:41        # tests overlapping 12..30, or spanning 41
+$ padded_cell -n /refund/ -e test_slow     # Minitest's --include / --exclude
+$ padded_cell -j 8 --seed 1234             # 8 workers, reproducible order
+$ padded_cell --timeout 30                 # kill and fail anything running 30s
+$ padded_cell --fail-fast
+$ padded_cell --list                       # what would run, without loading anything
+$ padded_cell --shard 2/4                  # CI: the second quarter of the classes
+$ padded_cell --junit tmp/junit.xml --json tmp/results.jsonl
+```
+
+Exit status: 0 when everything passed, 1 otherwise, 2 for usage or load
+errors, 130 when interrupted.
+
+### How a run works
+
+1. **Select** files the way `rails test` does, `file:line` included.
+2. **Discover** tests statically with Prism (`def test_*` and Rails'
+   `test "..."` in classes inheriting from a `...Test` or `...TestCase`).
+3. **Load** the test files once, in the runner. Workers and cells are forks of
+   that process, so the app boots once, and copy-on-write shares its memory.
+   `minitest/autorun` is neutralized, so the suite does not run again at exit.
+4. **Order**: keep each class's tests together, as Minitest and Rails do.
+   Shard by a stable hash of the class name, shuffle classes and tests with
+   the seed, then put the slowest classes, and within them the slowest
+   tests, first (`tmp/padded_cell/timings.tsv`).
+5. **Run**: a worker takes a whole class; once no class is left to take, an
+   idle worker splits off the second half of another worker's remainder.
+   Each test sends back its `Minitest::Result`. A cell or worker that dies or
+   times out becomes an error result.
+6. **Report** through Minitest's own reporters and plugins.
+
+Loaded tests are the source of truth: inherited, `define_method` and other
+dynamic tests run even though static discovery cannot see them.
+
+### Isolation
+
+`--isolation test` forks a cell per test. Forking a preloaded process is
+cheap, and order-dependent tests stop depending on order.
+
+`--isolation worker` runs tests directly in the long-lived workers, like
+Rails' `parallelize`. A worker that crashes or times out is still reported
+and replaced.
+
+The default is `test`, except when Active Record fixtures are loaded: a fork
+discards Active Record's connection pool, and every test would reload its
+fixtures, so those suites default to `worker`. The `Run options:` line shows
+which one a run uses; `--isolation` overrides it.
+
+### Hooks
+
+For anything that must not be shared across forks:
+
+```ruby
+# test/test_helper.rb
+PaddedCell.before_fork { Database.disconnect }
+PaddedCell.after_fork { |worker| Database.connect("app_test_#{worker}") }
+PaddedCell.cleanup { |worker| Database.drop("app_test_#{worker}") }
+```
+
+`before_fork` runs in the runner, `after_fork` and `cleanup` once per worker
+(`0...jobs`). Cells run no hooks: they inherit their worker's state.
+
+## Rails
+
+Nothing to configure. ActiveSupport's parallelization hooks run around
+padded_cell's workers as they would around Rails' own: `parallelize_setup`,
+`parallelize_teardown`, `parallelize_before_fork`, and Active Record's
+per-worker test databases (`app_test-0`, `app_test-1`...).
+`ActiveSupport::TestCase.parallel_worker_id` is set. A
+`parallelize(workers: ...)` call in `test_helper.rb` stays inert, since
+padded_cell is the executor.
+
+```console
+$ bin/rails padded_cell ARGS="-j 8 test/models"
+```
+
+Rails suites with fixtures run with `--isolation worker` unless told
+otherwise (see [Isolation](#isolation)).
+
+Coverage tools that write their results from an `at_exit` hook (SimpleCov)
+see only the runner, as with Rails' process parallelization.
+
+## Library
+
+The engine-backed parts load without Minitest:
+
+```ruby
+require "padded_cell"
+
+PaddedCell::Discovery.call(Dir["test/**/*_test.rb"]).map { [it.id, it.lines] }
+# => [["UserTest#test_valid", 10..12], ...]
+
+PaddedCell::Scheduler.batches(class_names, durations: seconds, seed: 42, shard: [0, 4])
+# => [[test indices of one class], ...] in run order
+```
+
+## Rust
+
+The extension lives in `ext/padded_cell_native`: `core` does discovery and
+scheduling in plain Rust (no Ruby types), `ffi` binds it to Ruby. Neither is
+published as a crate.
+
+## Development
+
+Needs Rust 1.99+ (`mise install` reads `mise.toml`).
+
+```console
+bundle install
+rake test:all        # cargo test, then the Ruby suite (compiles the extension first)
+rake test            # the Ruby suite only
+rake dogfood         # this suite, run by padded_cell
+rake lint            # dictator, cargo fmt --check, clippy
+```
+
+## License
+
+MIT

data/exe/padded_cell

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'padded_cell/cli'
+
+exit PaddedCell::CLI.start(ARGV)

data/ext/padded_cell_native/core/Cargo.toml

@@ -0,0 +1,20 @@
+[package]
+name = "padded_cell"
+version = "0.1.0"
+description = "Static Minitest discovery and test scheduling for the padded_cell gem"
+publish = false
+edition.workspace = true
+rust-version.workspace = true
+authors.workspace = true
+license.workspace = true
+repository.workspace = true
+
+[lints]
+workspace = true
+
+[dependencies]
+ruby-prism.workspace = true
+thiserror.workspace = true
+
+[dev-dependencies]
+tempfile.workspace = true

data/ext/padded_cell_native/core/README.md

@@ -0,0 +1,50 @@
+# padded_cell
+
+Static Minitest discovery and deterministic test scheduling: the Rust core of
+the padded_cell gem's native extension (`../ffi` binds it to Ruby). Internal,
+not published. It has no Ruby types: parse test files with
+[Prism](https://github.com/ruby/prism) and plan a sharded, seeded,
+longest-first run.
+
+```rust
+let source = br#"
+class UsersControllerTest < ActionDispatch::IntegrationTest
+  test "index lists users" do
+    get users_url
+  end
+
+  def test_show
+  end
+end
+"#;
+
+let found = padded_cell::discover(source);
+let ids: Vec<String> = found.iter().map(|test| test.id()).collect();
+assert_eq!(ids, ["UsersControllerTest#test_index_lists_users", "UsersControllerTest#test_show"]);
+let first = found.iter().next().ok_or("no test")?;
+assert_eq!((first.start_line, first.end_line), (3, 5));
+assert_eq!(found.classes(), ["UsersControllerTest"]); // stored once
+
+// One batch per class, slowest first. Shard 1 of 2, seed 42, no timings yet
+// (-1.0 means unknown).
+let classes: Vec<&str> = found.iter().map(|test| test.class_name).collect();
+let batches = padded_cell::plan(&classes, &[-1.0, -1.0], 42, 0, 2);
+assert!(batches.iter().flatten().all(|&index| index < ids.len()));
+# Ok::<(), Box<dyn std::error::Error>>(())
+```
+
+- `discover` finds `def test_*` methods and Rails `test "..."` declarations in
+  classes whose superclass ends in `Test` or `TestCase`, with their line
+  spans. Nothing is evaluated, and syntax errors do not stop it. Each class
+  name is stored once; tests borrow it.
+- `discover_files` reads and parses many files across cores, on scoped
+  threads (a process can fork right after). `discover_many` does the same for
+  sources already in memory.
+- `plan` keeps tests grouped by class (per-class setup such as fixtures loads
+  once), shards classes by FNV-1a hash, shuffles with SplitMix64, and puts
+  the slowest classes, and within them the slowest tests, first. Class names
+  are any bytes (`AsRef<[u8]>`).
+
+## License
+
+MIT

data/ext/padded_cell_native/core/src/discover/tests.rs

@@ -0,0 +1,107 @@
+use std::assert_matches;
+use std::io::ErrorKind;
+
+use super::*;
+
+fn ids(source: &str) -> Vec<String> {
+    ids_of(&discover(source.as_bytes()))
+}
+
+#[test]
+fn test_classes_are_named_by_their_superclass() {
+    let cases: &[(&str, &[&str])] = &[
+        ("class ATest < Minitest::Test\n def test_a; end\nend", &["ATest#test_a"]),
+        ("class B < ActiveSupport::TestCase\n def test_b; end\nend", &["B#test_b"]),
+        ("class C < BaseTest\n def test_c; end\nend", &["C#test_c"]),
+        ("class DTest < Object\n def test_d; end\nend", &[]),
+        ("class ETest\n def test_e; end\nend", &[]),
+        ("class FTest < Testing\n def test_f; end\nend", &[]),
+    ];
+    for (source, expected) in cases {
+        assert_eq!(ids(source), *expected, "source: {source:?}");
+    }
+}
+
+#[test]
+fn rails_test_names_replace_whitespace_runs() {
+    // A no-break space is not Ruby's \s: it stays.
+    let source = concat!(
+        "class ATest < ActiveSupport::TestCase\n",
+        "  test \"a \\t\\v\\f\\r\\n b\u{a0}c\" do\n",
+        "  end\n",
+        "end",
+    );
+    assert_eq!(ids(source), ["ATest#test_a_b\u{a0}c"]);
+}
+
+#[test]
+fn lines_are_one_based_and_span_the_definition() {
+    let source = "class ATest < Minitest::Test\n\n  def test_a\n    x\n  end\n  test 'b'\nend\n";
+    let found = discover(source.as_bytes());
+    let lines: Vec<_> = found.iter().map(|test| (test.start_line, test.end_line)).collect();
+    assert_eq!(lines, [(3, 5), (6, 6)]);
+}
+
+#[test]
+fn class_names_are_stored_once_and_only_with_tests() {
+    let source = concat!(
+        "class BaseTest < Minitest::Test\nend\n",
+        "module Admin\n  class ATest < BaseTest\n    def test_a; end\n    test 'b'\n  end\nend\n",
+    );
+    let found = discover(source.as_bytes());
+    assert_eq!(found.classes(), ["Admin::ATest"]);
+    assert_eq!(found.iter().map(|test| test.class).collect::<Vec<_>>(), [0, 0]);
+    assert_eq!(found.iter().len(), 2);
+}
+
+#[test]
+fn invalid_utf8_names_are_skipped() {
+    let source = "class ATest < Minitest::Test\n  test \"\\xFF\" do\n  end\nend";
+    assert_eq!(ids(source), Vec::<String>::new());
+}
+
+#[test]
+fn discover_many_keeps_input_order() {
+    let sources: Vec<String> = (0..64)
+        .map(|i| format!("class T{i}Test < Minitest::Test\n def test_{i}; end\nend"))
+        .collect();
+    let found = discover_many(&sources);
+    assert_eq!(found.len(), sources.len());
+    for (i, discovery) in found.iter().enumerate() {
+        assert_eq!(ids_of(discovery), [format!("T{i}Test#test_{i}")]);
+    }
+}
+
+#[test]
+fn discover_files_keeps_input_order() {
+    let dir = tempfile::tempdir().unwrap();
+    let paths: Vec<PathBuf> = (0..32)
+        .map(|i| {
+            let path = dir.path().join(format!("t{i}_test.rb"));
+            fs::write(&path, format!("\nclass T{i}Test < Minitest::Test\n  test '{i}'\nend\n"))
+                .unwrap();
+            path
+        })
+        .collect();
+    let found = discover_files(&paths).unwrap();
+    for (i, discovery) in found.iter().enumerate() {
+        let tests: Vec<_> = discovery.iter().map(|test| (test.id(), test.start_line)).collect();
+        assert_eq!(tests, [(format!("T{i}Test#test_{i}"), 3)]);
+    }
+}
+
+#[test]
+fn discover_files_reports_the_first_unreadable_file() {
+    let dir = tempfile::tempdir().unwrap();
+    let readable = dir.path().join("a_test.rb");
+    fs::write(&readable, "").unwrap();
+    let first_missing = dir.path().join("b_test.rb");
+    let paths = [readable, first_missing.clone(), dir.path().join("c_test.rb")];
+    let error = discover_files(&paths).unwrap_err();
+    assert_eq!(error.path, first_missing);
+    assert_matches!(error.source.kind(), ErrorKind::NotFound);
+}
+
+fn ids_of(discovery: &Discovery) -> Vec<String> {
+    discovery.iter().map(|test| test.id()).collect()
+}