specguard-rspec

The Ruby client for SpecGuard: an RSpec formatter that ships test-run telemetry, and a CLI linter that validates @intent annotations.

Two independent tools, one dependency — the OpenTestIntent annotation format.

Install

# Gemfile
group :test do
  gem "specguard-rspec", require: false
end

The linter — `specguard-lint`

Validates # @intent: annotations in changed (or all) *_spec.rb files against the OpenTestIntent JSON Schema. Exits 1 on a malformed annotation; never fails on a missing one (adoption is opt-in and gradual).

bundle exec specguard-lint --changed   # CI mode: only files in the current diff
bundle exec specguard-lint             # one-off audit: every *_spec.rb

Files are positional (specguard-lint spec/order_spec.rb); there is no --source flag — that belongs to the reference tool, not to this one.

The linter is an independent implementation of the same protocol, and its agreement with the reference is checked by running the two side by side rather than asserted in a comment: tests/parity/run_ruby_parity.sh in open-test-intent runs specguard-lint and the Go validator over a shared corpus and requires identical findings, ordering and exit codes. A handful of differences are ratified as such there, each with its reason and each asserted to still differ; everything else matches byte for byte. They are the same ones described under the backend below — two read failures, a parse-failure message, and one that is not about wording at all.

Machine-readable output (`--json`)

The human report is for humans. --json emits one JSON document on stdout instead, so a CI step or an agent gets which file, which line, which rule as data rather than a prose format to regex and a 3-valued exit code. The flag can go anywhere on the command line.

bundle exec specguard-lint --json spec/models/order_spec.rb

{
  "schema": "open-test-intent.v1.json",
  "mode": "source",
  "ok": false,
  "summary": { "files": 1, "annotations": 2, "failed": 2 },
  "findings": [
    { "file": "spec/models/order_spec.rb", "line": 24, "ok": false, "kind": "schema",
      "errors": ["<root>: additional property 'entiity' is not allowed"] },
    { "file": "spec/models/order_spec.rb", "line": 31, "ok": false, "kind": "extraction",
      "errors": ["unterminated object literal (an annotation must fit on one line)"] }
  ]
}

This is the same document validate-intent --json --source emits, key for key — the gem already consumes it when the Go backend is on, and a consumer of both tools should not need two parsers for one protocol. It is not byte-identical (Ruby does not escape non-ASCII where Python's json.dumps does); it is key-, type- and value-identical, which is what a parser sees.

field	meaning
`schema`	the OpenTestIntent schema version the payloads were validated against
`mode`	always `"source"` — annotations in spec sources, the port's name for what this tool does. Not the selection mode (`--changed` vs named files), which the document has no field for
`ok`	whether the run passed — derived from the exit code, not recomputed, so the two renderers cannot disagree
`summary.files`	spec files selected: the number the text report's leading `checked N spec file(s)` line states
`summary.annotations`	annotation sites examined: the number its trailing summary line states. A site whose payload could not be captured or parsed still counts; a file that could not be read contributes none
`summary.failed`	findings with `"ok": false`, read failures included. Note this is not the text summary's `M malformed`, which counts malformed annotations and reports unread files in its own clause

Every finding has the same five keys:

field	meaning
`file`	the path, echoed back exactly as it was given
`line`	the annotation's line number; `null` where the finding is not line-scoped — a read failure saw no line of the file, and `file:0` would point CI annotations and editor quickfix at a line that does not exist
`ok`	whether this finding passed
`kind`	how it failed; `null` when it passed
`errors`	every violated rule, or the single problem — always a list of strings, never null and never a bare string, so a consumer never branches on its type

kind is the field the prose renderer destroys: a failed extraction and an unparseable payload both read as one sentence after FAIL … — , and only kind tells them apart.

`kind`	means
`schema`	parsed fine, violated the OpenTestIntent schema
`extraction`	an `@intent:` token whose object literal could not be captured (missing or unbalanced braces, or spread across lines)
`parse`	the payload was captured but is not JSON even after normalisation
`read`	the file could not be read at all (missing, unopenable, or not valid UTF-8), so no annotation in it was ever seen

The port has a fifth kind, no-match, that cannot appear here: its arguments are globs and this tool's are paths, so a path that matches nothing is a read failure of that path.

Three things worth knowing:

Exit codes are identical with and without the flag, and the default output is unchanged. --json is a second renderer over the same checks, not a second code path — it is pinned that way in spec/specguard/rspec/exit_contract_spec.rb and spec/specguard/rspec/regression_targets_spec.rb.
A run that could not produce verdicts emits no document. Bad flags, --changed outside a repository, an unloadable schema, an unmet --require-validator — all still exit 2 with prose on stderr. Those runs checked nothing, and {"ok": false, "findings": []} is exactly how a gate that checked nothing gets mistaken for one that found nothing.
The provenance line stays on stderr and is deliberately not duplicated into the document (see below). Redirect 2> to keep it; stdout is the document and nothing else.

Optional: the Go validator as a backend

Set SPECGUARD_VALIDATE_INTENT to a validate-intent binary and specguard-lint will hand the selected files to it (--source --json) instead of validating them in Ruby, then render the same report from its findings:

SPECGUARD_VALIDATE_INTENT=/path/to/validate-intent bundle exec specguard-lint --changed

Off by default. The binary is not shipped with this gem and is not published anywhere yet, so the Ruby path stays the default and stays supported — this is for people who already build or vendor the validator and would rather run one implementation than two. A blank value counts as unset.

Naming a binary that is missing or unusable is already a hard failure (exit 2) rather than a quiet fall back to Ruby. What is not caught by that is never naming one at all — see --require-validator below.

`--require-validator` — assert that the binary actually ran

SPECGUARD_VALIDATE_INTENT=/path/to/validate-intent bundle exec specguard-lint --changed --require-validator

Exits 2 unless SPECGUARD_VALIDATE_INTENT named a usable binary, before any file is selected or checked:

specguard-lint: validated in Ruby (SPECGUARD_VALIDATE_INTENT is unset)
specguard-lint: error: --require-validator was given, but SPECGUARD_VALIDATE_INTENT is unset, so this run would have been validated in Ruby

Without the flag nothing changes: the backend stays opt-in, and a run with the variable unset is byte-identical to what it always was.

The case this exists for is the one the exit code alone cannot show you: a mistyped variable name, a conditional CI step that did not run, an environment file that was not loaded. The run succeeds — validated by the other implementation — and the only trace is a line on stderr that nothing reads. That is not "same answer, different engine": the two backends' JSON parsers do not accept the same language (see "The difference that is not about wording", below), so on a payload one accepts and the other rejects the two exit codes disagree, and a report with no findings is exactly what a clean run looks like.

It is a flag rather than a second environment variable on purpose. SPECGUARD_VALIDATE_INTENT_REQURED=1 would be silently no assertion at all — the same bug one level up. A mistyped --requre-validator cannot fail open; it exits 2.

--require-validator --help and --require-validator --version still exit 0. The flag asserts something about a run, and neither of those is one.

Every run says which implementation validated it

Because the two backends produce the same report, the report alone cannot tell you which one ran. So specguard-lint states it, in one line on stderr, on every run and on both arms:

specguard-lint: validated by validate-intent 1.4.0 (go1.22.12 linux/arm64) schema sha256:6535d9ba… at /path/to/validate-intent (SPECGUARD_VALIDATE_INTENT) — it reports enforcing the schema this gem vendors, loaded from /usr/local/schemas/open-test-intent.v1.json
specguard-lint: validated in Ruby (SPECGUARD_VALIDATE_INTENT is unset)
specguard-lint: validated in Ruby (SPECGUARD_VALIDATE_INTENT is set but blank, which means off)

The two "validated in Ruby" wordings are the same two --require-validator reports its refusal with, so one vocabulary describes both. The clause after the backend line is the schema-contract comparison — see "Which schema the run enforces", below.

The schema sha256: token in the first line is elided above only to fit; it prints in full, and it is part of the binary's own --version answer rather than something specguard-lint appends. A backend line without that token is a different band, and is worded differently.

Three things worth knowing about it:

stdout is untouched. The line is on stderr, beside the other diagnostics about the linter itself, so the findings and the two checked … lines are still byte-identical across the two backends and still safe to pipe. Under --json it stays exactly where it is and is not copied into the document: that would be the first key by which this gem's document differs from the port's, and it would give provenance two homes that can disagree about one fact — the hole this line was added to close, not to widen.
The identity is the binary's own. It comes from <binary> --version, asked once per run before any file is selected, and is passed through verbatim rather than reworded — that is the only thing that can tell two builds of the validator apart.
A binary that cannot answer still validates. --version and --schema-source each arrived in a later slice of the validator; a build without one reads the flag as a filename and exits 1. That costs nothing — same findings, same exit code, same stdout — and the line says which question went unanswered, in words (… which could not report its identity, so the schema contract it carries could not be checked) rather than going missing.

Which schema the run enforces

The identity line is not only printed. specguard-lint compares the schema this gem vendors — digested from the file at runtime — against the schema the binary reports, before any file is selected or checked, and refuses the run when the two differ.

Which digest it asks for is the whole of this check. validate-intent --version ends schema sha256:<64-hex>, the digest of the JSON Schema compiled into that binary — and that is not the schema a run necessarily loads. A schemas/open-test-intent.v1.json sitting beside the executable takes precedence over the compiled-in copy, and --version answers above that decision and never reaches it; the binary's own --help says the digest "is not a claim about what a given run enforced". So specguard-lint asks validate-intent --schema-source, which runs the real loader and reports the origin and digest of the bytes a verdict run would enforce, and compares that. Both questions are asked once per run, before any file is selected or checked.

This is the one thing about the pair that neither half can check by itself. Both sides already pin their own schema against their own tree, and both stay green while disagreeing with each other: the gem is installed from RubyGems, the binary is built or fetched by version separately, and nothing ties the two vintages together. What that produces is a run that succeeds under a contract other than the one this gem ships — and on the backend path the gem never loads its own schema at all, so no finding, count or exit code downstream can reflect the difference.

The run enforces the schema this gem vendors. It proceeds, and the line names where that schema came from — an absolute path when a file beside the binary won, or <embedded schema> when the compiled-in copy did:

specguard-lint: validated by validate-intent 1.4.0 (…) at /path/to/validate-intent (SPECGUARD_VALIDATE_INTENT) — it reports enforcing the schema this gem vendors, loaded from <embedded schema>

It enforces a different one. Exit 2, before any file is selected or checked:

specguard-lint: error: the validator backend at /path/to/validate-intent (SPECGUARD_VALIDATE_INTENT) reports enforcing schema sha256:9c1e…, loaded from /usr/local/schemas/open-test-intent.v1.json, but this gem vendors sha256:6535… — the two halves would enforce different contracts, so this run would produce a verdict this gem cannot stand behind; the binary identifies itself as validate-intent 1.5.0 (go1.22.12 linux/arm64) schema sha256:6535…

Both digests are printed in full (elided above only to fit), because one of them lives inside a binary and the other inside an installed gem and neither is inspectable from where the other lives. The origin is there because it says which half to move: a stale <embedded schema> is fixed by rebuilding or reinstalling the binary, and a path on this host by replacing or deleting that file. The version string is there for the question that follows immediately — which build is this — since on this path the provenance line above never prints. Note the identity in the example above carries the digest the gem vendors: a binary can be built against the right schema and still enforce the wrong one, which is exactly the case this comparison exists to catch.

This is a new way for a run to fail, and it can fail a job that was green yesterday without anything in your repository changing: upgrading the gem or the binary, or dropping a schema file beside the binary, is enough. That is the intended behaviour, and it is the same judgement --require-validator makes one level up — a verdict produced under a contract this gem does not ship is one it declines to launder. To fix it, move whichever half is stale so the two agree.

The binary is too old to be asked. --schema-source arrived in a later slice of the validator; an older build reads it as a filename and exits 1, and a schema that exists beside the binary and will not load exits 2 with its own "could not load schema" diagnostic (which the run reaches a moment later anyway, from the path that owns it). Neither costs a verdict. The comparison falls back to the carried digest — the same two outcomes, proceed or exit 2 — and the line keeps the hedge that belongs to that weaker question, because on that path it is still true:

specguard-lint: validated by validate-intent 1.2.0 (…) at /path/to/validate-intent (SPECGUARD_VALIDATE_INTENT), which reports carrying the schema this gem vendors — the contract it carries, not necessarily the one this run enforced

No digest to compare. Never a refusal — same findings, same exit code, same stdout — and the provenance line says which kind of "could not check" it was, in its own words:

…, which reports no schema digest, so the contract it carries could not be checked — a build older than the slice that added the token. The rule that an older binary must not cost you a verdict is unchanged here.
…, which could not report its identity, so the schema contract it carries could not be checked — a build too old to answer --version at all.
…, whose schema contract could not be checked: this gem could not read its own vendored copy — the gem's own installation is missing or unreadable. This is not fatal on this path on purpose: the backend run does not otherwise read that file, and a missing operand is an unanswered question, not a disagreement. (On the Ruby path the same file being unreadable is still exit 2, because there it is the contract the run is about to enforce.)

"Could not check" and "checked and clean" are different statements, so they are worded differently rather than both reading as silence.

What the backend does not change: the selection, the report format, or the summary-line format. What it can change is narrower than an earlier version of this section claimed, and the difference is worth stating precisely rather than reassuringly.

For every payload both JSON parsers accept, the two backends agree completely: the same finding against the same file at the same line, the same classification, the same counts and the same exit code. The messages in the table below differ in their trailing text only — the rows are the enumeration, not a sample of it, and each is asserted in both directions, so closing one fails the suite rather than leaving a stale claim here — in spec/specguard/rspec/validator_backend_spec.rb and in the parity harness above:

input	Ruby path	Go backend
a payload that is still not JSON after normalisation	`unexpected token at '{ "entity": …'`	`Expecting value: line 1 column 102 (char 101)`
a file that is not valid UTF-8	`invalid UTF-8 byte sequence`	the validator's own decoder message
a path that does not exist	`No such file or directory @ rb_sysopen - …`	`no file at this path`
a path that is not a regular file	`Is a directory @ io_fread - …`	`no file at this path`

The first row is the one you are most likely to actually see: parse is one of the three things the linter reports, and every malformed-JSON annotation renders differently under the backend. The Ruby path interpolates Ruby's JSON::ParserError; the validator reproduces CPython's json diagnostic, and the backend passes that through unaltered rather than inventing a third spelling. Both agree on which annotation broke, and on the line and column — only the prose moves. The other rows are read failures and need an unreadable path to reach at all.

The difference that is not about wording

The two JSON parsers do not accept the same language. CPython's json — which the validator reproduces deliberately — accepts two things Ruby's JSON.parse refuses:

the non-finite literals NaN, Infinity and -Infinity;
a high surrogate escape (\ud800–\udbff) with nothing escaped after it — either last in the string, or followed by a literal character. Ruby rescues it as soon as another \uXXXX escape follows, without requiring that escape to be a genuine low surrogate.

The list was three entries until the json gem changed underneath it, and the third is worth recording rather than deleting: Ruby used to refuse nesting past max_nesting: 100 at a depth CPython accepted, and used to require a real low surrogate. Both narrowed, so the set shrank — which is the direction it is expected to move, and the specs pin the new boundary exactly (see spec/specguard/rspec/validator_backend_spec.rb) so the next shift is caught the same way.

The membership was derived rather than guessed: 89,108 documents, including every one of the 65,536 single \uXXXX escapes, through both parsers. (A lone low surrogate is fine on both — the rule is narrower than "surrogate escapes".) The sweep is also symmetric: the other direction — documents Ruby accepts and CPython refuses — was swept too and is empty, so the list above is the whole difference between the two parsers and not just the half we went looking for. That matters, because a member of the reverse set would show up as the mirror of the first shape below: the Ruby path reporting a schema violation where the backend reports a parse failure.

On such a payload the backend does not word the failure differently; it does not have the same failure. It parses the payload and validates it, so you get a schema violation with -> reason lines where the Ruby path gives you one — could not parse annotation: line. The file, the line, the counts and the exit code still agree.

And if that payload is otherwise schema-valid — reachable only through the surrogate case, since a number and a container cannot fill a slot the schema declares as a string — the backend finds nothing wrong and exits 0 where the Ruby path exits 1. This is the one input on which the two backends disagree about whether your suite passes. It is enumerated and asserted from both sides, in the same places as the rows above.

Both are ratified rather than fixed, and the reason is scope: allow_nan: true and max_nesting: false would close the non-finite case, but the surrogate case has no such option and would mean porting CPython's string decoder into this gem — and both would change what the default Ruby path does, which the slice that added this backend deliberately holds fixed. See Scanner#parse for the full reasoning; whether the gem should adopt CPython's acceptance grammar is left open there rather than settled.

If you go and count them. The parity harness numbers this same enumeration two ways, and both numbers are correct, so it is worth saying which is which before you follow the link. It asserts them as six entries, (i)–(vi), under "8b. the six enumerated backend differences" — the rows of the table above, plus the two shapes the acceptance set takes. It groups them in its header as four mechanisms, (a)–(d), because the two unreadable-path rows share one cause and the two acceptance-set shapes share another. Six entries, four mechanisms, one enumeration.

Those two totals live in that harness, which asserts them. This page does not restate them beside the table, because a count kept in two places is a count that will eventually disagree with itself — which is exactly how an earlier revision of this section came to announce three messages directly above four rows.

Every way the backend can fail — the binary is missing, will not execute, exits with something that is not a verdict, or emits output that is not a report — is exit 2, the linter's "could not do my job" code. It never becomes exit 1, which means "an annotation is malformed" and nothing else.

The formatter — `SpecGuard::RSpecFormatter`

An additive RSpec formatter: it runs alongside your usual one (progress, documentation, …) rather than replacing it, and records every example that finished — annotated or not — as one JSON object per run, POSTed to SpecGuard (or written to log/test_results.jsonl when there is no API key).

# spec/spec_helper.rb
require "specguard/rspec/formatter"
RSpec.configure do |config|
  config.add_formatter(SpecGuard::RSpecFormatter)
end

# ...or in .rspec — the --require is not optional, RSpec cannot guess this path
--require specguard/rspec/formatter
--format SpecGuard::RSpecFormatter

The two forms are equivalent, and neither needs you to name a human formatter. Additive is meant literally, in both directions: if you chose a formatter that reports the run to a human (progress, documentation, --format failures, --format json, …), it is left alone and SpecGuard adds nothing to your output; if you chose none, you get RSpec's default (progress) exactly as you would without this gem — same dots, same failures, same summary, byte for byte.

The qualifier on that first half is deliberate. SpecGuard restores the default when no other registered formatter would give a human an account of the run, and it judges that by the formatter protocol — whether anything answers to example_started, example_passed, example_failed, example_pending or dump_summary. So if the only other formatter you registered is a silent one (another telemetry gem, a custom notifier that writes elsewhere), SpecGuard reads the run as unserved and restores progress, and you get output you did not have before. That is the error direction chosen on purpose — noisy beats silent, which is the whole point of this behaviour — but if you want a genuinely quiet run, name a formatter that reports the run and says little: --format failures prints one line per failure and nothing else, so a green suite stays at zero bytes and the restore does not fire.

That second half is not free, because RSpec installs its default formatter only when no formatter was registered at all — so a gem that registers one silently suppresses it, and a failing suite prints nothing. SpecGuard restores it on the first notification of the run, once RSpec has finished deciding. If you want something other than progress, name it the usual way (--format documentation, or config.default_formatter = "doc") and that is what you will get, on its own.

"Byte for byte" is checked rather than asserted: spec/specguard/rspec/formatter_run_spec.rb runs each wiring and the same suite with no SpecGuard at all, and diffs the two streams end to end with only the two wall-clock numbers erased. Both a failing suite and a suite that reports through reporter.message — an error in an after(:context) hook — are compared that way, because they travel through different formatters and an addition that is invisible in one shows up in the other.

Each example contributes its id, spec_file_path, file_path, line_number, name (the composed describe/context/it string), duration, outcome, status ("annotated" or "unannotated") and intent — the parsed annotation when there is one, null when there is not; the run envelope carries commit_sha, branch and duration_seconds.

id is RSpec's own example id — ./spec/orders_spec.rb[1:2], the argument that re-runs that one example — and it is the key that distinguishes examples a coordinate cannot. A table-driven loop writes its it once, so all of its examples share a line_number; a shared example group reports the coordinate of spec/support/shared.rb from every file that includes it. spec_file_path is the spec file that actually ran the example, which is the same as file_path for an ordinary example and the including file for a shared one — so duration-by-file adds up against the file you would have named, not against a spec/support/ helper.

id is unique within a run, not stable across refactors: it is positional, so reordering examples changes it, exactly as inserting a line changes line_number. Matching one test across runs is name plus file.

file_path and line_number keep meaning the definition site — that is the line the @intent: annotation is read from.

An example counts as annotated when an @intent: sits on its it line, or on the comment line immediately above it:

# @intent: { entity: "Order", action: "refund", behavior: "restores stock levels on refund", layer: "unit" }
it "restores stock on refund" do

it "surfaces the decline reason" do # @intent: { entity: "Order", action: "checkout", ... }

One line of lookback, no more — and a trailing annotation belongs to its own example only, never to the one on the next line.

A malformed or schema-invalid annotation is recorded as unannotated, with a null intent, and the formatter says nothing about it. That is deliberate: telemetry must never block CI, and the platform validates a run's payload as a whole — so shipping one bad annotation would cost the entire run its telemetry rather than one row its metadata. specguard-lint is the half of this gem that tells you about a bad annotation, loudly, with exit code 1. Run it in CI and the formatter never has anything to hide.

# optional — the defaults read the commit, branch, CI run id and shard index
# from whichever provider is running you (GitHub Actions, GitLab CI, CircleCI,
# Buildkite, Jenkins), and when none of them named the commit or the branch,
# ask git directly for both — so a laptop run and a hand-rolled container
# report their checkout too, without being configured to. A detached checkout
# reports no branch rather than the string "HEAD".
# SPECGUARD_COMMIT_SHA / SPECGUARD_BRANCH / SPECGUARD_RUN_ID /
# SPECGUARD_SHARD_ID / SPECGUARD_OUTPUT_PATH override any of it.
#
# Assign a value here only when it is one neither source can know:
SpecGuard::RSpec.configure do |config|
  config.branch = "release/2.0"
end

Shipping the run to SpecGuard

Set an API key and an endpoint and the run is POSTed to <endpoint>/api/v1/ingest — once per process, as a single request (see If you shard your suite for what happens when there is more than one process):

export SPECGUARD_ENDPOINT=https://specguard.example.com
export SPECGUARD_API_KEY=…          # from your repository's settings
export SPECGUARD_TIMEOUT=10         # optional; seconds, applied to connect and read

# ...or in Ruby, if you would rather not use the environment
SpecGuard::RSpec.configure do |config|
  config.endpoint = "https://specguard.example.com"
  config.api_key  = ENV["SPECGUARD_API_KEY"]
  config.timeout  = 10
end

The API key is the switch. With no key nothing is sent anywhere and the run is written to log/test_results.jsonl exactly as before — so local development needs no opt-out, and a fork with no secret configured behaves like a laptop rather than like a broken build.

A failed delivery is never silent, and never lost. If the endpoint refuses the run (a 401 from a rotated key, a 400, a 500) or cannot be reached at all (connection refused, DNS failure, timeout), the formatter prints one line to stderr naming the status or the error, and writes the payload to log/test_results.jsonl so the run can be replayed later:

SpecGuard: could not deliver test telemetry (HTTP 401 — the API key was not
accepted). Falling back to log/test_results.jsonl; the test run is unaffected.

There are no retries, and the whole delivery is bounded by timeout (10 seconds by default, against Net::HTTP's own 60): telemetry is explicitly allowed to be lost, and a retry would only double what a hung endpoint can cost your CI run.

A dry run is refused, to both sinks. rspec --dry-run builds and reports every example without executing a single body, so its per-example duration is the cost of constructing an example (single-digit microseconds — a sleep 0.05 example understates its own runtime by three to four orders of magnitude) and its outcome is passed for code that never ran. Nothing downstream can tell the difference, and an all-green, near-instant run is exactly the shape that poisons both the numbers SpecGuard reports. So when RSpec is in dry-run mode the formatter makes no POST and writes no line to log/test_results.jsonl — a file full of zero-duration green runs is the same corruption, deferred until something replays it — and says so once:

SpecGuard: skipped test telemetry for a dry run (rspec --dry-run executes no
example bodies, so this run's durations and outcomes would not be
measurements). Nothing was sent or written; the test run is unaffected.

This matters most where you are least likely to look for it: an API key is usually an environment-level secret rather than a job-level one, so a lint job that runs rspec --dry-run to catch an unparseable spec file inherits the key and would otherwise overwrite your suite's real duration and pass/fail picture with zeroes and green.

It never blocks CI. RSpec does not sandbox formatters — an exception raised in one escapes the runner and takes RSpec's own exit code with it — so every hook rescues, warns once on stderr, and leaves the exit status to your suite alone. A non-2xx response gets the same treatment: Net::HTTP returns those as ordinary values rather than raising, so they are checked for explicitly instead of being left to a rescue that would never see them.

If you shard your suite

parallel_tests, Knapsack and a CI matrix all run the suite as several processes, and each one loads this formatter and POSTs its own slice. The run id is what tells SpecGuard those POSTs are one run: shards that share it are accumulated onto a single record, so a 20,000-example suite reports a 20,000 denominator instead of one record per shard holding a quarter of it — and a quarter is what the dashboard showed before, attributed to the right commit, with nothing to mark it as partial.

Every supported provider publishes an id for the build (GITHUB_RUN_ID, CI_PIPELINE_ID, CIRCLE_WORKFLOW_ID, BUILDKITE_BUILD_ID, BUILD_TAG), so a sharded job on any of them needs no configuration. If you shard somewhere else, export one yourself — any value that every shard of the run shares and no other run repeats:

export SPECGUARD_RUN_ID="$MY_CI_BUILD_ID"

Unset is not an error. A run with no id is treated as a run of its own, which is exactly right for bundle exec rspec on a laptop. A genuinely different run — a nightly, a later push — gets a different id from its provider and stays a separate record, which is why the commit alone cannot do this job.

Re-runs, and why each shard also names itself

A CI run id does not change when you re-run the build. GitHub's own wording for GITHUB_RUN_ID is "This number does not change if you re-run the workflow run"; Buildkite retries a job inside the same BUILDKITE_BUILD_ID and GitLab inside the same CI_PIPELINE_ID. That is the behaviour SpecGuard wants — press "re-run failed jobs" on a sharded suite and only the failed shards run again, so they need to land back on the run they came from rather than forming a new run holding a fifth of the suite.

For that to be right, a shard has to be able to replace its own earlier numbers instead of adding to them, which means naming itself. SpecGuard reads the shard index your runner already exports:

Runner	Variable
`parallel_tests`	`TEST_ENV_NUMBER` (its blank first process is read as shard `1`)
GitLab `parallel:`, Knapsack Pro	`CI_NODE_INDEX`
CircleCI `parallelism:`	`CIRCLE_NODE_INDEX`
Buildkite `parallelism:`	`BUILDKITE_PARALLEL_JOB`

GitHub Actions matrix: is the one that needs a line of config. It exports no per-leg index — GITHUB_JOB is the job's id in your YAML and is identical across every leg — so set it from the matrix value:

strategy:
  matrix:
    shard: [1, 2, 3, 4]
steps:
  - run: bundle exec rspec
    env:
      SPECGUARD_SHARD_ID: ${{ matrix.shard }}

The value only has to be unique within one run; it is never compared across runs. Do the same if you nest — parallel_tests inside a matrix leg repeats TEST_ENV_NUMBER across legs, so give SPECGUARD_SHARD_ID something that composes both.

Leaving it unset is not an error and does not lose the slice: an unnamed shard is still counted into the run. What it cannot do is be recognised on a second delivery, so if that shard is retried its numbers are added again rather than replacing what was there. If your suite shards and you re-run it, name the shards.

What SpecGuard collects

Everything below is the whole of it. Transport#deliver sends the payload verbatim — there is no filtering layer between what the formatter captures and what leaves the machine — so this list is the request body, and a spec pins it so that adding a field without updating this section fails the build. A run big enough to be worth compressing is gzipped in transit; that changes how the body is encoded on the wire, never what is in it.

The run envelope — six fields, once per process:

Field	What it holds	Where it comes from
`commit_sha`	the commit the suite ran against	`SPECGUARD_COMMIT_SHA` if you set it, else `GITHUB_SHA`, `CI_COMMIT_SHA`, `CIRCLE_SHA1`, `BUILDKITE_COMMIT`, `GIT_COMMIT`, else `git rev-parse HEAD`
`branch`	the branch name; `null` on a detached checkout	`SPECGUARD_BRANCH` if you set it, else `GITHUB_REF_NAME`, `CI_COMMIT_REF_NAME`, `CIRCLE_BRANCH`, `BUILDKITE_BRANCH`, `GIT_BRANCH`, else `git symbolic-ref --short -q HEAD`
`ci_run_id`	your provider's build id, so shards of one run fold together; `null` on a laptop	`SPECGUARD_RUN_ID` if you set it, else `GITHUB_RUN_ID`, `CI_PIPELINE_ID`, `CIRCLE_WORKFLOW_ID`, `BUILDKITE_BUILD_ID`, `BUILD_TAG`
`shard_id`	which slice of that run this process is; `null` when unsharded	`SPECGUARD_SHARD_ID` if you set it, else `TEST_ENV_NUMBER`, `CI_NODE_INDEX`, `CIRCLE_NODE_INDEX`, `BUILDKITE_PARALLEL_JOB`
`duration_seconds`	wall clock for the whole run	measured by the formatter
`specs`	one object per example that finished — the nine fields below	the run

Each example — nine fields, one object per example, annotated or not:

Field	What it holds	Where it comes from
`id`	RSpec's own example id, `./spec/orders_spec.rb[1:2]` — the re-run argument	`example.id`
`spec_file_path`	the spec file that ran the example, relative to the project root when it lives under it — an absolute path when it does not, because a spec outside the working directory has no relative name	`metadata[:rerun_file_path]`
`file_path`	the spec file the example is defined in, on the same terms	`metadata[:file_path]`
`line_number`	the line it is defined on	`metadata[:line_number]`
`name`	the composed `describe`/`context`/`it` string	`example.full_description`
`duration`	seconds that one example took	`execution_result.run_time`
`outcome`	`passed`, `failed` or `pending`	`execution_result.status`
`status`	`annotated` or `unannotated`	whether an `@intent:` was found for that line
`intent`	the parsed `@intent:` annotation; `null` when there is none	the annotation you wrote in the spec file

Two request headers say something about you rather than about the request: the API key travels as a bearer token in Authorization, and User-Agent names this gem and its version (specguard-rspec/<version>), so the platform can tell its clients apart. The rest are ordinary HTTP plumbing that describe the message itself and carry nothing about your code or your suite — Content-Type, Accept, Content-Length, Host, Accept-Encoding, and Content-Encoding: gzip on a run large enough to be compressed. A spec pins that header set too, so a header added later cannot quietly slip past this paragraph.

Test names and annotations are free text, and that is the point

name and intent are written by your developers, in prose; file_path and spec_file_path are the names they gave the files. They will carry internal product detail — feature names, customer names, the shape of work you have not shipped — because a suite describes the system it tests.

The paths are the one part of this that is not authored but machine-derived, and it is worth knowing where that can go further than you meant. A spec under the project root reports a project-relative name and nothing more. A spec run from outside it has no relative name, so its real location is what travels — /home/build-agent-07/…, /var/lib/jenkins/workspace/acme-payments-nightly/… — in spec_file_path, in file_path, and in id, which is that same path plus a position. Ordinary suites never hit this; a spec vendored outside the tree, a shard splitter that expands its arguments to absolute paths, or an IDE runner will. That discloses a build machine's directory layout, which is a different category from prose, so it is named here rather than folded into the paragraph above.

SpecGuard is built on that and cannot be built without it. The product answers "what does this suite actually cover, and where are the gaps" — a question whose entire input is what your tests say they cover. A mode that shipped anonymised coordinates would not be a lighter SpecGuard; it would be a SpecGuard that cannot answer anything. So there is no opt-out, no field-level redaction and no name-scrubbing switch, and none is planned. This is a deliberate product decision, stated here so you can make yours.

If this cannot leave your perimeter, run SpecGuard inside it

Self-hosting is the supported answer, and it needs no code change — point SPECGUARD_ENDPOINT at your own deployment and every byte described above goes there instead:

export SPECGUARD_ENDPOINT=https://specguard.internal.example.com

What is never collected

No source code. Not your application's, and not your tests' — no example body, no let, no fixture, no diff of any of it.
No failure messages and no backtraces. A failing example contributes the string failed and nothing else; the exception, its message and its stack stay on your machine.
No test output. Nothing your suite printed to stdout or stderr, and nothing any other formatter wrote, is read or forwarded.
No environment. SpecGuard's own code reads a fixed list of variables and no others: the ones named in the envelope table above, which fill commit_sha, branch, ci_run_id and shard_id; plus four that configure the gem itself rather than describing your suite — SPECGUARD_ENDPOINT (where to send the run), SPECGUARD_OUTPUT_PATH (where to write the local file when there is no key), SPECGUARD_TIMEOUT (how long to wait), and SPECGUARD_API_KEY, which leaves the machine only as the bearer token described above. The other three are never sent, and there is no general environment capture to be caught by. (The linter is a separate program that sends nothing at all; it reads one variable of its own, SPECGUARD_VALIDATE_INTENT, documented above.)
One exception, and it is about the route rather than the contents: your proxy settings are read. Sending the run goes through Ruby's Net::HTTP, which resolves a proxy from the environment the way every Ruby HTTP client does — so if your network requires a proxy, the run takes it, without SpecGuard being told about it. http_proxy (or HTTP_PROXY) is the variable that does it, including for an https:// endpoint: Net::HTTP resolves the proxy against an http URL whatever the transport, which means setting only https_proxy will not proxy your run. no_proxy (or NO_PROXY) suppresses it per host. In a CGI environment (REQUEST_METHOD set) CGI_HTTP_PROXY is read instead and the uppercase spelling is ignored. None of these is ever transmitted, and none of them changes a byte of what is sent — they decide only where it goes, which is worth knowing alongside "If this cannot leave your perimeter, run SpecGuard inside it" above, since SPECGUARD_ENDPOINT is not the only thing that determines the destination.