Run Order & Filtering

## Defined order is the default Out of the box, rspec-core 3.13 runs example groups and examples in the order they are **defined**: files in load order, groups and examples top to bottom. That is predictable, and it is also how order dependencies hide: an example that only passes because an earlier one left a record in the database, a stubbed constant, or a memoised global behind will pass forever in defined order. ## Turning random order on Three equivalent switches exist: - `config.order = :random` in `spec_helper.rb` (suggested, commented out, in the template `rspec --init` writes); - `--order rand` or `--order random` on the command line; - the same `--order` line in `.rspec`. Other values are `defined`, `recently-modified` (most recently changed files first), and, since 3.13, the name of a custom strategy registered with `config.register_ordering`. When both are present, the command line and options files win: an `--order` or `--seed` option is forced, so a later `config.order =` in `spec_helper.rb` does not override it. ## Reading and replaying the seed Every random run chooses a seed (a random integer below 65,535 unless you give one) and prints it with the summary: ``` Randomized with seed 4821 ``` To replay that run: ``` rspec --seed 4821 ``` `--seed 4821` is documented as equivalent to `--order rand:4821`, so it also switches random ordering on even if the project normally runs in defined order. ## What gets shuffled, and what does not Random ordering is applied level by level, not across the whole suite at once: - top-level groups are ordered by the strategy; - inside a group, its own examples are ordered and run, then its nested groups, each ordered the same way; - examples from two different groups are never interleaved, so a `before(:context)` hook still runs once per group. A single group can opt out with metadata: `RSpec.describe Legacy::Importer, order: :defined do` keeps that group's examples in written order while the rest of the suite stays random. That is a documented escape hatch for code you cannot fix yet, not a fix; the dependency it hides is still there. ## How the shuffle is computed rspec-core does not use Ruby's global random generator for ordering. It sorts each list of groups or examples by a Jenkins hash of the seed concatenated with the item's id (such as `./spec/notifier_spec.rb[1:3]`). Two properties follow: 1. the same seed and the same set of examples always give the same order; 2. running a **subset** with the same seed keeps the surviving examples in the same relative order, which is what makes rerunning two ids, or `--bisect`, reproduce a failure. ## Seeding Ruby's own randomness RSpec deliberately never calls `srand`, so specs that use `rand`, `Array#shuffle` or `Array#sample` get fresh randomness each run. The template's suggestion ties that to the same seed: ```ruby RSpec.configure do |config| config.order = :random Kernel.srand config.seed end ``` With it, `--seed 4821` replays both the example order and the random data. ## Scenario: fails only in one order A suite passes on most runs and fails on a few, always with different seeds. The workflow: 1. copy the seed from the failing run's output, locally or from CI; 2. rerun with `rspec --seed <that seed>` and confirm the failure reproduces; 3. rerun the failing example alone with the same seed; if it passes, something that runs before it is leaking state; 4. hand the reproducing command to `--bisect` to find which example that is; 5. to prove the suite works when the leak is absent, run `rspec --order defined`. ## Common mistakes - Committing a fixed `config.seed = 1234`: every run then uses one order and the point of randomising is lost. - Expecting `--seed` to replay `rand` calls without `Kernel.srand config.seed`. - Reading the seed from a different run than the one that failed.