rspec-hopper 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7ac7938a8f8be5dfeaa3fe71e48c5f9a09ef34db00b94903a8e89e0862399571
-  data.tar.gz: 2f5f71d073fb570c482fd5d57a326cebf5a32e5a444d8a074ec729b4726cd09d
+  metadata.gz: 38c293f2c7a326a8b7ee5cd6883a72f392b55855eff1ad33a4863453dd6bc98a
+  data.tar.gz: a104e430ab3d22c8c8494a561fd57175039dadf3aed0a4b6f3f709f0e9e9a901
 SHA512:
-  metadata.gz: 3f8b0fe48942ad2724c23cea372d4a2ebf86bb7008d0e43f9300633f90e54f8ced37a81036c519fa2c0554d2df08582aab8af2f0210c5a1ea443468dc3137efc
-  data.tar.gz: 9ce47aee0f8525833c9974a77482ccd010439be6b904cf996086bd5664b14e82d4ac1865e418160481bf0c6166691b6d46ba67c623e98a5c587613099381baaa
+  metadata.gz: 77aaec88287312fa7460729c951a4bb0e2c976fbaff9ace8dd2142d3a9dace14ca72218397d7cbc7447b7bdd3a2269a29fdc8ed8bf5d635617806f3fe8579f6d
+  data.tar.gz: f2b139cacf77e4b95cebd2b01f74948999360c32cfad10b4c70bb295f3b3b3dfed427bc2c8ff0ad82b851e7146c9f3d898be497d9a30e011d5349ba14abe47e5

data/CHANGELOG.md

@@ -2,6 +2,26 @@
 
 ## [Unreleased]
 
+## [0.2.0] - 2026-09-13
+
+- A Rails example application under `examples/rails-app`, with its own bundle, that CI
+  drives through three shared-boot children in both unit modes: per-process SQLite
+  databases chosen by `TEST_ENV_NUMBER`, the README's fork hooks and database guard,
+  transactional tests, `before(:all)` records and a request spec.
+- `--unit example`: one work unit per selected example instead of per spec file.
+  Examples are queued in the order RSpec would run them under the build seed, run
+  through their file's group with the selection narrowed to the one example (context
+  hooks fire per unit), and a requeue reruns only the failed example. The unit type is
+  part of the suite fingerprint, is recorded in the manifest and the report summary
+  (`unit_type`), and `--failed-out` then lists example ids. `--unit file` stays the
+  default and its Redis layout is unchanged apart from the new `unit_type` meta field.
+- `ExampleSubset`, the second sanctioned touch of rspec-core internals, guarded by a
+  contract spec like `ExampleReset`.
+- Warn at boot when a gem wraps `RSpec::Core::Runner#run_specs`, which the worker's
+  runner replaces: that wrapper never runs, and for datadog-ci it is where the test
+  session and module are started. Documents starting such lifecycles in suite hooks.
+- Point the gem's `documentation_uri` at the design document.
+
 ## [0.1.0] - 2026-09-11
 
 - Initial Phase 1 implementation: file-level work units distributed through

data/README.md

@@ -1,13 +1,16 @@
 # rspec-hopper
 
+[![Gem Version](https://badge.fury.io/rb/rspec-hopper.svg)](https://badge.fury.io/rb/rspec-hopper)
+[![CI](https://dl.circleci.com/status-badge/img/gh/prsimp/rspec-hopper/tree/main.svg?style=shield)](https://dl.circleci.com/status-badge/redirect/gh/prsimp/rspec-hopper/tree/main)
+
 rspec-hopper distributes an RSpec suite across many CI workers through a shared
 Redis, requeues flaky work, reclaims work from workers that die, and produces one
 authoritative pass/fail verdict for the whole build.
 
-A hopper feeds a machine continuously: workers pull spec files from a shared queue as
-fast as they finish them, and requeued files drop back in ahead of untouched work.
-There is no up-front partitioning, so a slow file or a slow machine only delays its
-own share of the work.
+A hopper feeds a machine continuously: workers pull spec files (or, with
+`--unit example`, single examples) from a shared queue as fast as they finish them,
+and requeued work drops back in ahead of untouched work. There is no up-front
+partitioning, so a slow file or a slow machine only delays its own share of the work.
 
 ## Problems it solves
 
@@ -21,8 +24,10 @@ exit with its own status" approach as it exists in other tools:
   run". The report tells them apart and only passes when a published manifest exists
   and every unit in it finalized as passed.
 - **Fighting other gems over RSpec internals.** Nothing is prepended onto
-  `RSpec::Core::Example#run`, `#start` or `#finish`, so instrumentation gems that do
-  (datadog-ci, rspec-retry and others) keep working.
+  `RSpec::Core::Example#run`, `#start` or `#finish`, so the per-example half of
+  instrumentation gems (datadog-ci, rspec-retry and others) keeps working. Anything
+  those gems wrap around `RSpec::Core::Runner#run_specs` is a different matter — see
+  [Instrumentation that wraps the runner](#instrumentation-that-wraps-the-runner).
 - **Ambiguous exit codes.** Workers exit 0 on completion regardless of test results;
   `rspec-hopper report` is the single place a build's verdict comes from.
 - **`Marshal.load` from a shared Redis.** Everything stored is JSON.
@@ -70,8 +75,13 @@ bundle exec rspec-hopper report \
 ```
 
 The report's exit code is the build's result. Use it as the CI job's status. The
-`--failed-out` file holds one spec file per line (failed and never-finalized units), so
-`bundle exec rspec $(cat tmp/hopper-failed.txt)` reruns them locally.
+`--failed-out` file holds one unit id per line (failed and never-finalized units): a
+spec file, or under `--unit example` an example id such as `./spec/foo_spec.rb[1:2]`.
+Either form is an argument `rspec` accepts, so this reruns them locally:
+
+```sh
+xargs bundle exec rspec < tmp/hopper-failed.txt
+```
 
 `--build`, `--worker` and `--redis` can be omitted when `HOPPER_BUILD_ID`,
 `HOPPER_WORKER_ID` and `HOPPER_REDIS_URL` (or `REDIS_URL`) are set, and the build and
@@ -84,13 +94,15 @@ worker, `<hostname>-<pid>` is used.
 1. Every worker boots the application and loads the spec files with RSpec, exactly as
    `rspec` would, applying `.rspec`, `~/.rspec`, `SPEC_OPTS` and the command line.
 2. The first worker to take a short lease publishes the build: one **unit** per spec
-   file that has at least one selected example, plus a manifest (unit and example
+   file that has at least one selected example (or per selected example, see
+   [Work units](#work-units-files-or-examples)), plus a manifest (unit and example
    counts, the file arguments, the suite fingerprint, the seed). Every other worker
    waits for the manifest, then checks that its own suite fingerprint matches. A
    worker that does not match exits 2 and names the inputs that differ.
 3. Workers loop: reclaim a unit whose owner stopped heartbeating, or reserve the next
-   unit (requeued units first), run all of that file's top-level example groups through
-   `ExampleGroup.run`, then finalize the unit as passed or failed, or requeue it.
+   unit (requeued units first), run it through `ExampleGroup.run` (all of a file's
+   top-level groups, or one example narrowed within its group), then finalize the unit
+   as passed or failed, or requeue it.
 4. Formatter output is buffered per attempt and replayed only for the final attempt,
    so JUnit and JSON files contain each example exactly once. Flakiness is recorded in
    the attempt log, not in formatter output.
@@ -124,6 +136,37 @@ These hold regardless of worker crashes, hung tests, or Redis trouble:
 - Redis, application or worker death and hung tests may delay completion; they cannot
   silently change the verdict or prevent completion indefinitely.
 
+## Work units: files or examples
+
+`--unit file` (the default) makes each spec file one unit. `--unit example` makes
+each selected example one unit, identified by its RSpec id
+(`./spec/models/foo_spec.rb[1:2:1]`). The choice belongs to the build: the unit type
+is part of the suite fingerprint, so a worker started with the other value exits 2
+naming `unit_type` as the differing input.
+
+Example units buy two things. Scheduling is finer, so one slow file no longer holds
+a worker while the others sit idle, and a requeue reruns only the example that
+failed rather than its whole file. What they cost:
+
+- **Context hooks run per example.** An example unit runs through its file's group
+  with the selection narrowed to that one example, so `before(:context)` and
+  `after(:context)` hooks on the path to the example fire once per unit, not once
+  per file. Sibling contexts that contain no selected example are skipped entirely.
+  A file whose `before(:all)` is expensive is a reason to stay with file units.
+- **Documentation-style formatters repeat group headers.** Each unit replays its own
+  `example_group_started` notifications, so the documentation formatter prints the
+  group description before every example. JUnit and JSON output are unaffected:
+  every example still appears exactly once.
+- **The manifest is larger.** It lists every unit id, about 40 bytes per example,
+  and the queue holds one entry per example. Redis handles tens of thousands of
+  entries comfortably; a suite of several hundred thousand examples should measure
+  before switching.
+
+Ordering is preserved. The publishing worker queues the examples in the order RSpec
+would have run them under the build seed, so `--order rand` still randomizes the
+sequence and `--seed` still reproduces it. Reclaims and requeues of individual
+examples do not change the order of the remaining queue.
+
 ## Suite hooks run once per worker process
 
 `before(:suite)` and `after(:suite)` run once in **every worker process**, not once per
@@ -134,6 +177,64 @@ workers start.
 
 A `before(:suite)` hook that raises makes that worker exit 2 without running any unit.
 
+### Instrumentation that wraps the runner
+
+The no-prepend promise covers `RSpec::Core::Example`. It does not extend to
+`RSpec::Core::Runner#run_specs`: the worker runs a `Runner` subclass that defines
+`run_specs` itself, driving the queue instead of `world.ordered_example_groups`, and a
+module prepended onto the superclass cannot intercept a method the subclass defines. Any
+gem whose session or reporting lifecycle lives in a `run_specs` wrapper will not have
+that wrapper run.
+
+datadog-ci is the case to know about. Its per-example patches still produce test spans,
+but `start_test_session` and `start_test_module` live in its `run_specs` wrapper, so
+without them every span is emitted with no session or module to belong to and Datadog
+drops the lot — `Event with type test(name=rspec.test) is invalid: test_session_id is
+required`. A worker prints a warning at boot when it finds such a wrapper, because the
+alternative is a green build reporting nothing.
+
+Start and finish that lifecycle in suite hooks instead. They run once per worker
+process, which is the same granularity each `parallel_tests` process had:
+
+```ruby
+# spec/support/datadog.rb
+RSpec.configure do |config|
+  config.before(:suite) do
+    Datadog::CI.start_test_session(service: "my-suite")
+    Datadog::CI.start_test_module("rspec")
+  end
+
+  config.after(:suite) do
+    # `with_suite_hooks` runs this from an `ensure`, so it also fires while the
+    # worker is unwinding from an infrastructure failure — Redis unreachable,
+    # `CORRUPT`, `meta` gone. No example failed in that case, so check for the
+    # exception in flight or the session finishes green on a worker that died.
+    failed = !$!.nil? || RSpec.configuration.reporter.failed_examples.any?
+
+    test_module = Datadog::CI.active_test_module
+    test_session = Datadog::CI.active_test_session
+    failed ? test_module&.failed! : test_module&.passed!
+    failed ? test_session&.failed! : test_session&.passed!
+    test_module&.finish
+    test_session&.finish
+  end
+end
+```
+
+By the time `after(:suite)` runs, the reporter holds every example this worker
+finalized: each attempt replays its buffer as the unit finalizes, and the whole unit
+loop sits inside the suite hooks.
+
+Three things to keep in mind. Each worker process opens its own session, so a build of
+ten workers reports ten sessions — Datadog's own guidance for `parallel_tests`-style
+parallelism — and which files land in which session changes run to run, because the
+queue hands out work dynamically. `force_test_level_visibility` must stay off: it
+disables the suite-level visibility these calls depend on, and they silently return
+`nil` with it on. And a worker that aborts a hung unit exits through `exit!`, which runs
+no `ensure` and therefore no `after(:suite)`: that worker's session is never finished,
+and its tests are lost to Datadog even though `rspec-hopper report` still counts the
+unit.
+
 ## CLI reference
 
 ### `rspec-hopper work`
@@ -148,8 +249,9 @@ rspec-hopper work --build ID --worker WID --redis URL [options] [rspec args...]
 | `--worker WID` | `$HOPPER_WORKER_ID`, CI inference, then `<hostname>-<pid>` | This worker's id, unique within the build. |
 | `--redis URL` | `$HOPPER_REDIS_URL`, then `$REDIS_URL` | Redis URL. |
 | `--revision SHA` | none | String mixed into the suite fingerprint, for example the commit being tested. |
+| `--unit TYPE` | `file` | What one queue entry is: `file` or `example`. See [Work units](#work-units-files-or-examples). |
 | `--timeout SECONDS` | 180 | Missed-heartbeat window after which an in-flight unit can be reclaimed by another worker. |
-| `--max-unit-duration SECONDS` | 900 | After this much execution time a unit is recorded as abandoned and becomes reclaimable even though its owner is alive; the owner aborts itself `--timeout` seconds later. Must exceed the slowest legitimate file. |
+| `--max-unit-duration SECONDS` | 900 | After this much execution time a unit is recorded as abandoned and becomes reclaimable even though its owner is alive; the owner aborts itself `--timeout` seconds later. Must exceed the slowest legitimate unit. |
 | `--max-requeues N` | 0 | Maximum number of retries of any one unit. |
 | `--requeue-tolerance R` | 0 | Fraction of units, `0.0` to `1.0`, allowed to enter retry during the build (`ceil(total_units * R)` units). |
 | `--max-reclaims N` | 3 | Reclaims from dead or abandoning owners before a unit is finalized as failed. |
@@ -164,9 +266,9 @@ Either retry limit at zero disables requeues; the defaults run every file once.
 retry, reclaim and timeout values of the worker that publishes the build are recorded
 in the build and enforced for every worker, so give all workers the same flags.
 
-Requeue eligibility: a failed attempt is requeued only if every failure in the file is
+Requeue eligibility: a failed attempt is requeued only if every failure in the unit is
 requeueable, meaning anything except `SystemExit`, `Interrupt`, `SignalException` and
-`NoMemoryError`. One of those anywhere in the file makes the attempt final. When a
+`NoMemoryError`. One of those anywhere in the unit makes the attempt final. When a
 retry would exceed `--max-requeues` or the tolerance, the failure is final with reason
 `retry_budget_exhausted`. On a requeue the worker prints one line and emits nothing to
 formatters:
@@ -182,7 +284,8 @@ wherever they come from (`.rspec`, `~/.rspec`, `SPEC_OPTS` or the command line):
 state or with distributed execution.
 
 The seed is chosen by the publishing worker (the user's `--seed` if given, otherwise
-random) and adopted by every worker, so within-file ordering is identical everywhere.
+random) and adopted by every worker, so within-file ordering is identical everywhere,
+and under `--unit example` the queue itself is in that order.
 
 ### `rspec-hopper report`
 
@@ -198,7 +301,7 @@ rspec-hopper report --build ID --redis URL [options]
 | `--init-timeout S` | 300 | Wait this long for the manifest or tombstone to appear before exiting 2. |
 | `--inactive-timeout S` | 300 | Give up (exit 3) once this long has passed since the later of the build becoming ready and the most recent worker activity. |
 | `--summary-out PATH` | none | Write the JSON summary to PATH. |
-| `--failed-out PATH` | none | Write failed and never-finalized unit ids to PATH, one per line. |
+| `--failed-out PATH` | none | Write failed and never-finalized unit ids to PATH, one per line (file paths or example ids, depending on the build's `--unit`). |
 | `--fail-on-empty` | on | Zero selected examples is a failure. |
 | `--allow-empty` | off | Zero selected examples may pass. Cannot be combined with a positive `--min-examples`. |
 | `--min-examples N` | 0 | Fail unless at least N examples were selected, guarding against a filter that selects almost nothing. |
@@ -210,7 +313,7 @@ count as worker activity, so a file slower than `--inactive-timeout` does not tr
 
 The JSON summary has these keys: `build_id`, `state`, `verdict` (`passed`, `failed`,
 `incomplete`, `init_failed`, `missing`, `expired`, `unreachable`), `exit_code`,
-`message`, `total_units`, `total_examples`, `finalized_count`, `failed` (unit id,
+`message`, `total_units`, `unit_type`, `total_examples`, `finalized_count`, `failed` (unit id,
 reason, worker id, errors), `flaky`, `never_finalized` (unit id, last worker id),
 `abandoned`, `retry_counts`, `reclaim_counts`, `worker_errors`, `stale_rejections`,
 `workers`, `load_errors`, `file_args`, `seed`, `fingerprint`, `revision`.
@@ -312,6 +415,10 @@ if defined?(RSpec::Hopper)
 end
 ```
 
+A runnable version of this recipe, with the guard below, is the Rails application under
+[`examples/rails-app`](examples/rails-app), which the gem's own CI drives through three
+shared-boot children.
+
 The hook receives the child's `TEST_ENV_NUMBER` value (`""` or `"2"`..`"N"`); it is
 also already set in `ENV`. Registering hooks in single-process or per-process mode is
 harmless; they are only run in shared mode.
@@ -324,7 +431,7 @@ first unit, and a failure there makes the worker exit 2:
 RSpec.configure do |config|
   config.before(:suite) do
     suffix = ENV.fetch("TEST_ENV_NUMBER", "")
-    database = ActiveRecord::Base.connection.current_database
+    database = ActiveRecord::Base.connection_db_config.database.to_s
     unless database.end_with?(suffix)
       raise "worker #{ENV["TEST_ENV_NUMBER"].inspect} is connected to #{database}"
     end
@@ -363,6 +470,30 @@ you point several children at the console yourself.
 With `--processes 1` (the default) nothing is redirected: one worker owns the console
 and prints its summary as plain `rspec` would.
 
+#### A single-process worker can look hung in CI
+
+RSpec's default `progress` formatter writes a bare dot per example with no newline.
+Nothing in the gem buffers — rspec-core sets `sync` on the output stream, and hopper's
+own lines (`initialized build ...`, `Retrying ...`, abort warnings) end in newlines — but
+a log viewer that renders whole lines has nothing to show between them. A worker that
+spends ten minutes on a queue of slow files therefore looks like it has stopped, and a
+CI no-output timeout has nothing to reset it with.
+
+If that matters on your CI, give the console a formatter that emits lines and send the
+machine-readable one to a file:
+
+```sh
+rspec-hopper work --build "$B" --worker "$W" --redis "$R" \
+  --format documentation \
+  --format RspecJunitFormatter --out "tmp/junit-$W.xml" -- spec
+```
+
+This is the `--processes 1` case, so name the file yourself — `%{n}` is substituted only
+for forked children, and a single-process run passes the arguments to RSpec untouched.
+Above one process the console formatter is redirected to a file anyway (see above), so
+only hopper's own lines reach the console, and the build's progress is better watched
+through `rspec-hopper report`.
+
 ## Retries, reclaims and per-unit counters
 
 Each unit carries three counters, all visible in the attempt log:
@@ -495,8 +626,14 @@ bundle exec rake          # specs, then rubocop
 Specs that need Redis are tagged `:redis`, use `HOPPER_TEST_REDIS_URL` (default
 `redis://127.0.0.1:6399/0`) and are skipped with a message when no server answers.
 Integration specs under `spec/integration` spawn real `rspec-hopper` processes against
-the fixture suites in `spec/fixtures/suites`. CI runs the suite on Ruby 3.2 through
-4.0 against Redis 7, plus Redis 6.2 and Valkey on the newest Ruby.
+the fixture suites in `spec/fixtures/suites`, and `spec/integration/rails_example_spec.rb`
+against the Rails application in `examples/rails-app`, which has its own bundle: run
+`bundle install` there once, or the spec skips itself. CircleCI runs the suite on Ruby 3.2
+through 4.0 against Redis 7, plus Redis 6.2 and Valkey on the newest Ruby, the Rails
+example once, and rubocop once (`.circleci/config.yml`). Each spec job writes a JUnit file that CircleCI stores,
+so slow and failing examples are visible per job rather than only in the log. Releases stay on GitHub Actions, because RubyGems
+trusted publishing authenticates that workflow's OIDC token; the release job runs the
+same suite before it publishes.
 
 ### Releasing
 
@@ -510,10 +647,10 @@ tree or a version that is already tagged.
 
 [trusted publishing]: https://guides.rubygems.org/trusted-publishing/
 
-## Phase 1 non-goals
+## Non-goals
 
-- Example-level units or splitting slow files; a unit is a whole spec file.
-- Retrying only the failed examples within a file; a requeue reruns the file.
+- Splitting a file into anything other than whole examples; there is no partial retry
+  of a file unit, a requeue reruns the whole unit.
 - Timing-based ordering or scheduling.
 - Metrics emission.
 - Compatibility with ci-queue's flags.

data/docs/DESIGN.md

@@ -23,6 +23,7 @@ lib/rspec/hopper/attempt_log.rb            Event + queries
 lib/rspec/hopper/manifest.rb
 lib/rspec/hopper/fingerprint.rb
 lib/rspec/hopper/example_reset.rb
+lib/rspec/hopper/example_subset.rb          narrows a group to one example around ExampleGroup.run
 lib/rspec/hopper/worker.rb                 the RSpec adapter: loop, init/election, completion
 lib/rspec/hopper/worker/suite.rb           loads RSpec, discovers units, option checks, seed adoption
 lib/rspec/hopper/worker/buffering_reporter.rb
@@ -39,9 +40,10 @@ exe/rspec-hopper
 spec/spec_helper.rb                        loads spec/support/**/*.rb
 spec/support/redis_helper.rb               TEST redis url, flush helper, key/TTL scan
 spec/rspec/hopper/**                       unit specs, mirror lib layout
-spec/contract/**                           example_reset, prepend coexistence
+spec/contract/**                           example_reset, example_subset, prepend coexistence
 spec/fixtures/suites/<name>/               fixture suites (each has .rspec, spec/, optional spec_helper)
 spec/integration/**                        spawn real `exe/rspec-hopper work` processes
+examples/rails-app/                        minimal Rails app with its own bundle; driven by spec/integration/rails_example_spec.rb
 ```
 
 Namespace is `RSpec::Hopper` (capital S). Runtime deps: rspec-core, redis, json only.
@@ -237,10 +239,13 @@ A unit reclaimed and then passing with no `requeued` event is not flaky.
 
 ## Manifest
 
-`Manifest = Data.define(:total_units, :total_examples, :file_counts, :file_args,
-:fingerprint, :fingerprint_digests, :seed, :ready_at, :revision, :load_errors)` —
-`#unit_ids` is derived: the
-keys of `file_counts` in order (`total_units == unit_ids.size`).
+`Manifest = Data.define(:total_units, :total_examples, :unit_type, :unit_ids, :file_counts,
+:file_args, :fingerprint, :fingerprint_digests, :seed, :ready_at, :revision, :load_errors)` —
+`unit_type` is `file` or `example`. For file units `unit_ids` defaults to the keys of
+`file_counts` in order and is not written to `meta`; for example units it is given
+explicitly (the example ids in queue order) and written as the JSON field `unit_ids`.
+`total_units == unit_ids.size` always; `file_counts` (selected examples per file) is
+kept for both types.
 `#to_meta` -> Hash of String->String for HSET (JSON-encoding the nested fields);
 `Manifest.from_meta(hash)` inverse (ignores the extra runtime fields). `ready_at` is
 epoch ms set by Redis; before publication it's nil.
@@ -261,19 +266,26 @@ children). Sequence:
    `configuration.load_spec_files`; `RSpec.world.wants_to_quit || rspec_is_quitting`
    with captured messages => `load_errors`. Any other exception during boot is phase
    `boot` -> exit 2.
-2. Units: `RSpec.world.ordered_example_groups` (top-level, in configured order); a unit
-   is every distinct `group.metadata[:file_path]` whose `descendant_filtered_examples`
+2. Units: `RSpec.world.ordered_example_groups` (top-level, in configured order); a file
+   unit is every distinct `group.metadata[:file_path]` whose `descendant_filtered_examples`
    is non-empty; file counts are `descendant_filtered_examples.size` summed per file;
-   unit id is `metadata[:file_path]` verbatim (`./spec/...`). Example ids for the
+   unit id is `metadata[:file_path]` verbatim (`./spec/...`). With
+   `config.unit_type == "example"` a unit is every selected example, id `example.id`
+   (`./spec/foo_spec.rb[1:2:1]`), in the order `ExampleGroup.run` would execute them:
+   per top-level group, `ordering_strategy.order(filtered_examples)` then
+   `ordering_strategy.order(children)` recursively, under this worker's seed (which is
+   the seed the initializer publishes). Example ids for the
    fingerprint are `example.id` over `RSpec.world.all_examples` filtered to the selected
    set (`group.descendant_filtered_examples` across all top-level groups).
-3. Fingerprint (`Fingerprint.compute(configuration:, options:, revision:)`): SHA256 over
-   a canonical JSON of `{file_args: sorted, filter: inclusion+exclusion rules as
+3. Fingerprint (`Fingerprint.compute(configuration:, options:, revision:, unit_type:)`):
+   SHA256 over a canonical JSON of `{file_args: sorted, filter: inclusion+exclusion rules as
    strings, pattern:, exclude_pattern:, order: configuration.ordering_registry ... name
    (`RSpec.configuration.ordering_manager` exposes `seed_used?`/`order`; derive the
    strategy name from `configuration.ordering_manager.instance_variable_get`? NO —
    use the merged option `options.options[:order]` string minus any `:seed` suffix, or
-   `"defined"` when absent), example_ids: sorted, revision:}`. Also returns the
+   `"defined"` when absent), example_ids: sorted, revision:, unit_type:}`. Including the
+   unit type is what stops a `--unit file` worker joining a `--unit example` build; the
+   mismatch message names `unit_type`. Also returns the
    `inputs` hash so a mismatch message can diff them (`Fingerprint::Mismatch#explain`).
 4. Election/join per product spec; `config.init_timeout` bounds it. After `ready`:
    compare fingerprint; `RSpec.configuration.seed = manifest.seed`.
@@ -288,9 +300,11 @@ children). Sequence:
    supervised, continue. With a reservation: `ExampleReset.reset(groups)` if
    `reservation.ownership_generation > 1` OR the process has run these groups before
    (simplest: always reset before running; the reset is idempotent on fresh examples —
-   do it always), start `Heartbeat`, run each top-level group for the unit through
-   `group.run(buffering_reporter)` in `ordered_example_groups` order, stop heartbeat,
-   then `RequeuePolicy.decide(examples)`.
+   do it always), start `Heartbeat`, run the unit via `Suite#run_unit`: each top-level
+   group of a file unit through `group.run(buffering_reporter)` in
+   `ordered_example_groups` order, or for an example unit its one top-level group inside
+   `ExampleSubset.scoped(group, [example])`; stop heartbeat, then
+   `RequeuePolicy.decide(examples)`.
 7. `RequeuePolicy`: collect `execution_result` of the unit's selected examples; failed
    examples' `exception` (and for `RSpec::Core::MultipleExceptionError`, `all_exceptions`)
    must all be requeueable (`not SystemExit/Interrupt/SignalException/NoMemoryError`);
@@ -337,6 +351,18 @@ ivar list after a run under bare rspec-core 3.13.6:
 `[:@clock, :@example_block, :@example_group_class, :@example_group_instance,
 :@exception, :@id, :@metadata, :@reporter]`.
 
+`ExampleSubset.scoped(root, examples) { root.run(reporter) }` — the second sanctioned
+touch of rspec-core internals (Phase 2). `ExampleGroup.run` takes what to run from
+`RSpec.world.filtered_examples[group]` and decides whether to run a group's context
+hooks from the memoized `@descendant_filtered_examples`. For every group in
+`root.descendants` the module saves both, replaces the world entry with the
+intersection with `examples` and clears the memo, yields, and restores both in an
+`ensure`. Nothing else; no method resolution changes. The contract spec asserts the
+hook behaviour (only hooks on the path to the example fire, siblings are skipped),
+restoration after an exception, that `ExampleGroup.filtered_examples` is the very
+object in the world hash, and pins the class ivar list of a run group under bare
+rspec-core 3.13.6 (`ExampleSubset::EXPECTED_GROUP_IVARS`).
+
 ## Report
 
 `Report.new(config:, queue:, clock:, sleeper:)`, `#run(out:)` -> exit code; `#summary`
@@ -360,13 +386,14 @@ never_finalized).
 ## Config
 
 ```ruby
-WorkConfig = Data.define(:build_id, :worker_id, :redis_url, :timeout, :max_unit_duration,
+WorkConfig = Data.define(:build_id, :worker_id, :redis_url, :unit_type, :timeout, :max_unit_duration,
   :max_requeues, :requeue_tolerance, :max_reclaims, :processes, :boot, :report_on_exit,
   :ttl, :tombstone_ttl, :init_timeout, :revision, :rspec_args, :report_args, :supervised)
 ReportConfig = Data.define(:build_id, :redis_url, :timeout, :init_timeout,
   :inactive_timeout, :summary_out, :failed_out, :allow_empty, :min_examples)
 ```
-Defaults live in `Config::DEFAULTS`. `boot` is `:per_process` or `:shared`.
+Defaults live in `Config::DEFAULTS`. `boot` is `:per_process` or `:shared`; `unit_type`
+is `"file"` or `"example"` (`--unit`).
 `rspec_args` is the array after the gem's own flags (everything OptionParser did not
 consume, plus everything after `--`). `report_args` are the raw args for the parent's
 `--report-on-exit` report (built from the work flags: build, redis).

data/lib/rspec/hopper/cli/work/parser.rb

@@ -73,6 +73,7 @@ module RSpec
             OptionParser.new do |o|
               o.banner = BANNER
               identity_options(o)
+              unit_options(o)
               policy_options(o)
               process_options(o)
               lifetime_options(o)
@@ -90,6 +91,14 @@ module RSpec
             opt.on("--revision SHA", "revision string mixed into the suite fingerprint") { |v| @opts[:revision] = v }
           end
 
+          def unit_options(opt)
+            opt.separator ""
+            opt.separator "Work units:"
+            opt.on("--unit TYPE", UNIT_TYPES, "what one queue entry is: file (default) or example") do |v|
+              @opts[:unit_type] = v
+            end
+          end
+
           def policy_options(opt)
             opt.separator ""
             opt.separator "Requeue and timeout policy:"

data/lib/rspec/hopper/config.rb

@@ -6,7 +6,7 @@ module RSpec
     # collaborator; there is no global.
     WorkConfig = Data.define(
       :build_id, :worker_id, :redis_url,
-      :timeout, :max_unit_duration, :max_requeues, :requeue_tolerance, :max_reclaims,
+      :unit_type, :timeout, :max_unit_duration, :max_requeues, :requeue_tolerance, :max_reclaims,
       :processes, :boot, :report_on_exit,
       :ttl, :tombstone_ttl, :init_timeout, :revision,
       :rspec_args, :report_args, :supervised
@@ -18,6 +18,8 @@ module RSpec
       def heartbeat_interval
         [timeout / 3.0, 30.0].min
       end
+
+      def example_units? = unit_type == "example"
     end
 
     # Frozen configuration for the `report` subcommand.
@@ -32,7 +34,7 @@ module RSpec
 
     module Config
       WORK_DEFAULTS = {
-        build_id: nil, worker_id: nil, redis_url: nil,
+        build_id: nil, worker_id: nil, redis_url: nil, unit_type: "file",
         timeout: 180, max_unit_duration: 900, max_requeues: 0, requeue_tolerance: 0.0, max_reclaims: 3,
         processes: 1, boot: :per_process, report_on_exit: false,
         ttl: 14_400, tombstone_ttl: 604_800, init_timeout: 300, revision: nil,

data/lib/rspec/hopper/example_reset.rb

@@ -25,12 +25,16 @@ module RSpec
       # their descendants. Returns the number of examples reset.
       def reset(example_groups)
         Array(example_groups).sum do |group|
-          group.descendants.sum do |descendant|
-            descendant.filtered_examples.each { |example| reset_example(example) }.size
-          end
+          group.descendants.sum { |descendant| reset_examples(descendant.filtered_examples) }
         end
       end
 
+      # Resets exactly the given examples (an example unit's single example).
+      # Returns the number of examples reset.
+      def reset_examples(examples)
+        Array(examples).each { |example| reset_example(example) }.size
+      end
+
       def reset_example(example)
         example.instance_variable_set(:@exception, nil)
         example.metadata[:execution_result] = RSpec::Core::Example::ExecutionResult.new

data/lib/rspec/hopper/example_subset.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require "rspec/core"
+
+module RSpec
+  module Hopper
+    # Runs a subset of an example group's selected examples through the public
+    # `ExampleGroup.run`, which is how example units execute one example while
+    # its file's context hooks still fire around it.
+    #
+    # `ExampleGroup.run` takes what to run from `RSpec.world.filtered_examples`
+    # and memoizes `descendant_filtered_examples` per group, which decides
+    # whether a group's `before(:context)`/`after(:context)` hooks run at all.
+    # Both are private to rspec-core. This is the second sanctioned touch of
+    # RSpec internals, granted for Phase 2 alongside ExampleReset: it swaps two
+    # pieces of state around one `run` and restores them afterwards, changes no
+    # method resolution, and is guarded by a contract spec pinned to 3.12-3.13.
+    module ExampleSubset
+      # The group-level memo that `ExampleGroup.run` consults through
+      # `descendant_filtered_examples`; the contract spec pins its presence.
+      MEMO_IVAR = :@descendant_filtered_examples
+
+      # Class-level instance variables of a run example group, pinned under
+      # bare rspec-core by the contract spec so new group state in a future
+      # release fails loudly rather than silently escaping the swap.
+      EXPECTED_GROUP_IVARS = %i[
+        @before_context_ivars @children @currently_executing_a_context_hook @descendant_filtered_examples
+        @examples @hooks @metadata @parent_groups @superclass_metadata @user_metadata
+      ].freeze
+
+      module_function
+
+      # Narrows `root` and its descendants to `examples` for the duration of
+      # the block. Groups with none of them selected run no examples and no
+      # context hooks. Returns the block's value.
+      def scoped(root, examples)
+        groups = root.descendants
+        saved = groups.to_h { |group| [group, [world.filtered_examples[group], memo(group)]] }
+        groups.each do |group|
+          world.filtered_examples[group] = saved[group].first.select { |example| examples.include?(example) }
+          group.instance_variable_set(MEMO_IVAR, nil)
+        end
+        yield
+      ensure
+        saved&.each do |group, (filtered, memo)|
+          world.filtered_examples[group] = filtered
+          group.instance_variable_set(MEMO_IVAR, memo)
+        end
+      end
+
+      def memo(group) = group.instance_variable_get(MEMO_IVAR)
+
+      def world = RSpec.world
+    end
+  end
+end

data/lib/rspec/hopper/fingerprint.rb

@@ -8,9 +8,9 @@ module RSpec
     # Proves that workers loaded the same logical suite, not merely that they were
     # given the same arguments. Computed after loading, over the normalized
     # selection inputs, the ordering strategy name (never the seed), the sorted
-    # selected example ids and the optional revision string.
+    # selected example ids, the optional revision string and the unit type.
     class Fingerprint
-      INPUT_KEYS = %w[file_args filter pattern exclude_pattern order example_ids revision].freeze
+      INPUT_KEYS = %w[file_args filter pattern exclude_pattern order example_ids revision unit_type].freeze
       PROC_ADDRESS = /0x[0-9a-f]+@?/
       # Per-input digests are recorded in the manifest so a mismatching worker
       # can name the inputs that differ. Truncated: they are compared with each
@@ -25,7 +25,8 @@ module RSpec
         # @param example_ids [Array<String>] ids of the selected examples
         # @param file_args [Array<String>] normalized file arguments
         # @param revision [String, nil]
-        def compute(configuration:, options:, example_ids:, file_args:, revision: nil)
+        # @param unit_type [String] "file" or "example"; a build has one unit type
+        def compute(configuration:, options:, example_ids:, file_args:, revision: nil, unit_type: "file")
           filter_manager = configuration.filter_manager
           new(
             "file_args" => Array(file_args).map(&:to_s).sort,
@@ -37,7 +38,8 @@ module RSpec
             "exclude_pattern" => configuration.exclude_pattern.to_s,
             "order" => ordering_name(options.options[:order]),
             "example_ids" => Array(example_ids).map(&:to_s).sort,
-            "revision" => revision&.to_s
+            "revision" => revision&.to_s,
+            "unit_type" => unit_type.to_s
           )
         end
 
@@ -123,7 +125,8 @@ module RSpec
           "exclude_pattern=#{inputs["exclude_pattern"].inspect}",
           "order=#{inputs["order"]}",
           "example_ids=#{inputs["example_ids"].size}",
-          "revision=#{inputs["revision"].inspect}"
+          "revision=#{inputs["revision"].inspect}",
+          "unit_type=#{inputs["unit_type"]}"
         ].join(", ")
       end
 

data/lib/rspec/hopper/manifest.rb

@@ -4,10 +4,11 @@ require "json"
 
 module RSpec
   module Hopper
-    # Written once by the initializing worker into `meta`. Unit ids are the keys
-    # of `file_counts` in order; they are not stored separately.
+    # Written once by the initializing worker into `meta`. For file units the
+    # unit ids are the keys of `file_counts` in order and are not stored
+    # separately; for example units they are stored as `unit_ids`.
     Manifest = Data.define(
-      :total_units, :total_examples, :file_counts, :file_args,
+      :total_units, :total_examples, :unit_type, :unit_ids, :file_counts, :file_args,
       :fingerprint, :fingerprint_digests, :seed, :ready_at, :revision, :load_errors
     ) do
       # Builds a Manifest from `meta` exactly as HGETALL returns it (all string
@@ -17,6 +18,8 @@ module RSpec
         new(
           total_units: meta.fetch("total_units"),
           total_examples: meta.fetch("total_examples"),
+          unit_type: meta.fetch("unit_type", "file"),
+          unit_ids: meta["unit_ids"] && JSON.parse(meta["unit_ids"]),
           file_counts: JSON.parse(meta.fetch("file_counts", "{}")),
           file_args: JSON.parse(meta.fetch("file_args", "[]")),
           fingerprint: meta["fingerprint"],
@@ -51,21 +54,35 @@ module RSpec
         }
       end
 
+      # File units are the files themselves, so their ids need not be given.
+      def self.unit_ids_for(type, unit_ids, counts)
+        ids = unit_ids || (type == "file" ? counts.keys : nil)
+        raise ArgumentError, "unit_ids are required for #{type} units" if ids.nil?
+
+        ids.map(&:to_s).freeze
+      end
+
       def self.presence(value)
         value.nil? || (value.respond_to?(:empty?) && value.empty?) ? nil : value
       end
 
-      def initialize(total_examples:, file_counts:, file_args:, fingerprint: nil, fingerprint_digests: nil,
-                     seed: nil, total_units: file_counts.size, ready_at: nil, revision: nil, load_errors: [])
+      def initialize(total_examples:, file_counts:, file_args:, unit_type: "file", unit_ids: nil, fingerprint: nil,
+                     fingerprint_digests: nil, seed: nil, total_units: nil, ready_at: nil, revision: nil,
+                     load_errors: [])
         counts = file_counts.to_h { |path, count| [path.to_s, Integer(count)] }.freeze
-        units = Integer(total_units)
-        if units != counts.size
-          raise ArgumentError, "total_units (#{units}) does not match file_counts.size (#{counts.size})"
-        end
+        type = unit_type.to_s
+        raise ArgumentError, "unknown unit type #{type.inspect}" unless UNIT_TYPES.include?(type)
+
+        ids = self.class.unit_ids_for(type, unit_ids, counts)
+        units = Integer(total_units || ids.size)
+        raise ArgumentError, "total_units (#{units}) does not match the number of unit ids (#{ids.size})" if
+          units != ids.size
 
         super(
           total_units: units,
           total_examples: Integer(total_examples),
+          unit_type: type,
+          unit_ids: ids,
           file_counts: counts,
           file_args: Array(file_args).map(&:to_s).freeze,
           load_errors: Array(load_errors).map(&:to_s).freeze,
@@ -74,22 +91,27 @@ module RSpec
         )
       end
 
-      def unit_ids = file_counts.keys
+      def file_units? = unit_type == "file"
+      def example_units? = unit_type == "example"
 
       def init_failed? = load_errors.any?
 
       def empty? = total_examples.zero?
 
       # Hash of String => String for HSET. Nested fields are JSON-encoded;
-      # nil fields are omitted rather than written as empty strings.
+      # nil fields are omitted rather than written as empty strings. File
+      # unit ids are implied by `file_counts` and not written, so the meta of
+      # a file-unit build is what 0.1.0 wrote plus `unit_type`.
       def to_meta
         meta = {
           "total_units" => total_units.to_s,
           "total_examples" => total_examples.to_s,
+          "unit_type" => unit_type,
           "file_counts" => JSON.generate(file_counts),
           "file_args" => JSON.generate(file_args),
           "load_errors" => JSON.generate(load_errors)
         }
+        meta["unit_ids"] = JSON.generate(unit_ids) unless file_units?
         optional_meta.each { |key, value| meta[key] = value unless value.nil? }
         meta
       end

data/lib/rspec/hopper/queue/redis_streams.rb

@@ -236,7 +236,7 @@ module RSpec
 
         def init_script(mode, token, manifest, unit_ids_json)
           fields = manifest.to_meta.merge(budget_meta)
-          argv = [mode, token, ms(ttl), ms(tombstone_ttl), JSON.generate(fields), unit_ids_json, "file"]
+          argv = [mode, token, ms(ttl), ms(tombstone_ttl), JSON.generate(fields), unit_ids_json, manifest.unit_type]
           run_script(:init, init_keys, argv)
         rescue Redis::CommandError => e
           code = e.message[/\A(?:ERR\s+)?([A-Z_]+)/, 1]

data/lib/rspec/hopper/report.rb

@@ -215,7 +215,8 @@ module RSpec
         return "unknown (no manifest)" unless @manifest
 
         finalized = @finalized_count.nil? ? "" : ", #{@finalized_count} finalized"
-        "#{@manifest.total_units} total#{finalized}; examples: #{@manifest.total_examples} selected"
+        "#{@manifest.total_units} #{@manifest.unit_type} units total#{finalized}; " \
+          "examples: #{@manifest.total_examples} selected"
       end
 
       def print_log_notes(out)
@@ -238,6 +239,7 @@ module RSpec
           "exit_code" => outcome.exit_code,
           "message" => outcome.headline,
           "total_units" => @manifest&.total_units,
+          "unit_type" => @manifest&.unit_type,
           "total_examples" => @manifest&.total_examples,
           "finalized_count" => @finalized_count,
           **log_summary,

data/lib/rspec/hopper/unit.rb

@@ -2,12 +2,25 @@
 
 module RSpec
   module Hopper
-    UNIT_TYPES = %w[file].freeze
+    UNIT_TYPES = %w[file example].freeze
 
-    # A schedulable unit of work. Phase 1 units are spec files; the `type`
-    # field exists so example-level units can be added without a schema change.
+    # A schedulable unit of work: one spec file (`file`, the default) or one
+    # example (`example`, `--unit example`). The `type` travels with the queue
+    # entry, the reservation and the manifest.
     Unit = Data.define(:id, :type) do
       def self.file(path) = new(id: path, type: "file")
+      def self.example(example_id) = new(id: example_id, type: "example")
+
+      def initialize(id:, type:)
+        type = type.to_s
+        raise ArgumentError, "unknown unit type #{type.inspect}; expected one of #{UNIT_TYPES.join(", ")}" unless
+          UNIT_TYPES.include?(type)
+
+        super(id: id.to_s, type: type)
+      end
+
+      def file? = type == "file"
+      def example? = type == "example"
 
       def to_h = { "id" => id, "type" => type }
     end

data/lib/rspec/hopper/version.rb

@@ -2,6 +2,6 @@
 
 module RSpec
   module Hopper
-    VERSION = "0.1.0"
+    VERSION = "0.2.0"
   end
 end

data/lib/rspec/hopper/worker/suite.rb

@@ -7,7 +7,8 @@ module RSpec
   module Hopper
     class Worker
       # Loads the RSpec suite once per process, rejects unsupported options,
-      # discovers file units, computes the fingerprint and adopts the build seed.
+      # discovers the units (`config.unit_type`), computes the fingerprint and
+      # adopts the build seed.
       # This is the only place that mutates RSpec.configuration.
       class Suite
         RUNNER_OPTIONS = {
@@ -48,6 +49,7 @@ module RSpec
           @err = err
           @load_errors = []
           @groups_by_file = {}
+          @unit_examples = {}
         end
 
         def configuration = RSpec.configuration
@@ -63,10 +65,7 @@ module RSpec
           reject_unsupported_configuration!
           normalize_file_args!
           load_spec_files
-          world.announce_filters
-          discover_units
-          @fingerprint = Fingerprint.compute(configuration: configuration, options: options, example_ids: example_ids,
-                                             file_args: file_args, revision: config.revision)
+          describe_loaded_suite
           self
         rescue InfrastructureError
           raise
@@ -74,13 +73,52 @@ module RSpec
           raise BootError, "#{e.class}: #{e.message}", e.backtrace
         end
 
+        # Modules prepended onto `RSpec::Core::Runner` that define `run_specs`.
+        # A prepend on the superclass cannot intercept a method the subclass
+        # defines, and the worker's Runner defines `run_specs` itself, so these
+        # never run here.
+        #
+        # @param base [Class] the class to inspect; injectable for specs
+        def self.runner_wrappers(base = RSpec::Core::Runner)
+          base.ancestors
+              .take_while { |mod| !mod.equal?(base) }
+              .select { |mod| mod.method_defined?(:run_specs, false) }
+              .map { |mod| mod.name || mod.inspect }
+        end
+
         def unit_ids = units.map(&:id)
+        def unit_type = config.unit_type
+        def example_units? = config.example_units?
+
+        # The top-level groups a unit runs through: every group of the file for
+        # a file unit, the one group containing the example for an example unit.
+        def groups_for(unit_id)
+          return @groups_by_file.fetch(unit_id, []) unless example_units?
+
+          group, _example = @unit_examples[unit_id]
+          group ? [group] : []
+        end
+
+        # Selected examples of the unit: the file's, including nested groups,
+        # or the one example.
+        def examples_for(unit_id)
+          return groups_for(unit_id).flat_map(&:descendant_filtered_examples) unless example_units?
 
-        # Top-level groups whose file is the unit, in configured order.
-        def groups_for(unit_id) = @groups_by_file.fetch(unit_id, [])
+          _group, example = @unit_examples[unit_id]
+          example ? [example] : []
+        end
 
-        # Selected examples of the unit, including nested groups.
-        def examples_for(unit_id) = groups_for(unit_id).flat_map(&:descendant_filtered_examples)
+        # Executes one unit through `ExampleGroup.run`, after resetting its
+        # examples so a retry in this process starts clean. An example unit
+        # narrows its group to the one example for the duration of the run.
+        def run_unit(unit_id, reporter)
+          groups = groups_for(unit_id)
+          examples = examples_for(unit_id)
+          ExampleReset.reset_examples(examples)
+          return groups.each { |group| group.run(reporter) } unless example_units?
+
+          ExampleSubset.scoped(groups.first, examples) { groups.first.run(reporter) }
+        end
 
         # Sets the build seed without changing the global ordering strategy:
         # `Configuration#seed=` switches an unforced global ordering to random,
@@ -112,6 +150,7 @@ module RSpec
         def to_manifest(revision: config.revision)
           Manifest.new(
             total_examples: total_examples, file_counts: file_counts, file_args: file_args,
+            unit_type: unit_type, unit_ids: unit_ids,
             fingerprint: fingerprint.value, fingerprint_digests: fingerprint.digests,
             seed: configuration.seed, revision: revision, load_errors: load_errors
           )
@@ -119,6 +158,34 @@ module RSpec
 
         private
 
+        # Everything that depends on the spec files being loaded: instrumentation
+        # is installed by then, and the units and fingerprint come from the
+        # groups the load produced.
+        def describe_loaded_suite
+          warn_about_runner_wrappers
+          world.announce_filters
+          discover_units
+          @fingerprint = Fingerprint.compute(configuration: configuration, options: options, example_ids: example_ids,
+                                             file_args: file_args, revision: config.revision,
+                                             unit_type: config.unit_type)
+        end
+
+        # The per-example patches such gems install still work — that is what
+        # the no-prepend promise is about — so the failure is otherwise silent:
+        # spans keep being produced with no session for them to belong to, and
+        # the build looks instrumented while reporting nothing.
+        def warn_about_runner_wrappers
+          wrappers = self.class.runner_wrappers
+          return if wrappers.empty?
+
+          @err.puts "[hopper #{config.worker_id}] #{wrappers.join(", ")} wraps " \
+                    "RSpec::Core::Runner#run_specs, which rspec-hopper replaces, so that wrapper will not " \
+                    "run. Instrumentation that starts there (datadog-ci's test session and module, for " \
+                    "one) must be started from a before(:suite) hook and finished in after(:suite): hopper " \
+                    "runs those once per worker process. See the README."
+          @err.flush if @err.respond_to?(:flush)
+        end
+
         def reject_init_option!
           env_args = ENV["SPEC_OPTS"] ? Shellwords.split(ENV["SPEC_OPTS"]) : []
           return unless (rspec_args + env_args).include?("--init")
@@ -195,9 +262,32 @@ module RSpec
             end
           end
                                         .freeze
-          @units = @file_counts.keys.map { |path| Unit.file(path) }.freeze
           @total_examples = @file_counts.values.sum
           @example_ids = @groups_by_file.values.flatten.flat_map(&:descendant_filtered_examples).map(&:id).sort.freeze
+          @units = (example_units? ? example_units : file_units).freeze
+        end
+
+        def file_units = @file_counts.keys.map { |path| Unit.file(path) }
+
+        # One unit per selected example, in the order RSpec would run them under
+        # this worker's configuration and seed (top-level groups as the world
+        # orders them, which interleaves files under random ordering), so the
+        # queue order is the ordering the initializer publishes with the seed.
+        def example_units
+          world.ordered_example_groups.each do |group|
+            next if group.descendant_filtered_examples.empty?
+
+            ordered_examples(group).each { |example| @unit_examples[example.id] = [group, example] }
+          end
+          @unit_examples.keys.map { |id| Unit.example(id) }
+        end
+
+        # A group's selected examples then its children's, each in the group's
+        # own ordering: the sequence `ExampleGroup.run` would execute.
+        def ordered_examples(group)
+          strategy = group.ordering_strategy
+          strategy.order(group.filtered_examples) +
+            strategy.order(group.children).flat_map { |child| ordered_examples(child) }
         end
       end
     end

data/lib/rspec/hopper/worker.rb

@@ -6,7 +6,8 @@ require_relative "worker/runner"
 module RSpec
   module Hopper
     # The RSpec adapter: loads the suite, joins or initializes the build, pulls
-    # units, runs each through `ExampleGroup.run`, decides requeue from the
+    # units, runs each through `ExampleGroup.run` (a file's groups, or one
+    # example narrowed within its group), decides requeue from the
     # execution results and forwards final attempts to the formatters.
     class Worker
       POLL_INTERVAL = 0.5
@@ -176,7 +177,7 @@ module RSpec
         outcome = phase(:execution, unit_id: unit_id) do
           raise InfrastructureError, "unit #{unit_id} is not part of this worker's suite" if groups.empty?
 
-          run_groups(groups, buffer, reservation)
+          run_unit(buffer, reservation)
         end
         decision = RequeuePolicy.decide(examples, escaped: outcome.escaped)
         phase(:execution, unit_id: unit_id) do
@@ -191,15 +192,14 @@ module RSpec
         alert "#{outcome.escaped.class} escaped an example in #{unit_id}; the unit was finalized as failed"
       end
 
-      def run_groups(groups, buffer, reservation)
-        ExampleReset.reset(groups)
+      def run_unit(buffer, reservation)
         heartbeat = Heartbeat.new(queue: queue, reservation: reservation, config: config, err: @err, clock: @clock,
                                   aborter: @aborter, worker_id: worker_id)
         started = @clock.call
         escaped = nil
         heartbeat.start
         begin
-          groups.each { |group| group.run(buffer) }
+          suite.run_unit(reservation.unit_id, buffer)
         rescue *RequeuePolicy::NON_REQUEUEABLE => e
           escaped = e
         ensure

data/lib/rspec/hopper.rb

@@ -14,6 +14,7 @@ require_relative "hopper/queue"
 require_relative "hopper/queue/redis_streams"
 require_relative "hopper/fingerprint"
 require_relative "hopper/example_reset"
+require_relative "hopper/example_subset"
 require_relative "hopper/worker/buffering_reporter"
 require_relative "hopper/worker/heartbeat"
 require_relative "hopper/worker/requeue_policy"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rspec-hopper
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Paul Simpson
@@ -91,6 +91,7 @@ files:
 - lib/rspec/hopper/config.rb
 - lib/rspec/hopper/errors.rb
 - lib/rspec/hopper/example_reset.rb
+- lib/rspec/hopper/example_subset.rb
 - lib/rspec/hopper/fingerprint.rb
 - lib/rspec/hopper/keys.rb
 - lib/rspec/hopper/manifest.rb
@@ -116,6 +117,7 @@ metadata:
   homepage_uri: https://github.com/prsimp/rspec-hopper
   source_code_uri: https://github.com/prsimp/rspec-hopper
   changelog_uri: https://github.com/prsimp/rspec-hopper/blob/main/CHANGELOG.md
+  documentation_uri: https://github.com/prsimp/rspec-hopper/blob/main/docs/DESIGN.md
   rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths: