Files and Artifacts

Document files Blackbox reads, writes, modifies, and expects teams to commit or ignore.

Abstract

This page tells you what lives in the workspace, what gets generated, what is ephemeral, and what is likely worth committing.

Audience

Developers deciding what to commit, what to ignore, what to archive from CI, and what to review when behavior changes.

Artifact Families

Blackbox has four artifact families:

Behavior specs: .feature files that make scenarios readable and reviewable.
Effect contracts: .effects.yaml files that declare required and forbidden runtime effects.
Runtime evidence: spans and V8 coverage captured from a real system-test run.
Reports: OMC/DC, catalog, shape, HTML, Markdown, JSON, XML, and CI-facing outputs.

The first two are usually reviewed like source. The last two are generated evidence and should be treated according to the workflow you choose.

Files Blackbox Reads

File or directory	Purpose	Usually committed?
`blackbox-testbed.ts`	Points Blackbox at the runnable topology, services, source directories, ports, and artifact directory.	Yes
`docker-compose.yml` or equivalent topology config	Starts the SUT and managed dependencies.	Yes
`e2e/features/*.feature`	Runtime-backed behavior spec surface.	Yes, if feature artifacts are part of review
`e2e/tests/__effects__/*.effects.yaml`	Effect catalog entries for required and forbidden behavior.	Yes
System-test files	Drive the workflow that creates evidence.	Yes
Service source directories	Used to resolve OMC/DC branch locations and snippets.	Yes, as normal source

Files Blackbox Writes

The default artifact directory in the showcase is .blackbox-coverage/. Your project may configure a different directory.

Artifact	What it means	Primary reader	Git policy
`.blackbox-coverage/omcdc-propagation.json`	Machine-readable OMC/DC propagation report.	Tools, CI, agents	Usually ignored; archive in CI when useful
`.blackbox-coverage/omcdc-propagation.md`	Markdown form of the OMC/DC report.	Humans in review or editor	Usually ignored, sometimes attached to PR/CI
`.blackbox-coverage/omcdc.html`	Interactive branch-by-branch OMC/DC report.	Humans debugging coverage	Ignore; publish or attach as CI artifact
`.blackbox-coverage/coverage.json`	Effect catalog coverage summary.	Tools and reviewers	Usually ignored; useful for CI comparison
`.blackbox-coverage/shape-coverage.json`	Boundary-shape coverage summary.	Tools and reviewers	Usually ignored; useful for CI comparison
`.blackbox-coverage/omcdc.junit.xml`	JUnit XML form when the JUnit reporter is enabled.	CI test report UI	Ignore; CI consumes it
`.blackbox-coverage/coverage-final.json`	Istanbul-compatible coverage data.	Coverage tooling	Ignore; archive when needed
`.blackbox-coverage/html/index.html`	Istanbul HTML coverage report.	Humans comparing code coverage	Ignore; publish or attach as CI artifact
`.blackbox-coverage/spans/*.json`	Per-test runtime spans collected from SUT debug endpoints.	Diagnostics, replay, agents	Ignore; archive only for debugging
`.blackbox-coverage/v8-per-test/*.json`	Per-test V8 coverage captured from SUT processes.	OMC/DC engine, replay	Ignore; archive only for debugging

Feature And Effect Files

Feature files and effect files are different artifacts and should not be collapsed into one mental bucket.

Feature files are the readable behavior surface. They explain the workflow in Given/When/Then-style language and are useful for review, product discussion, and stale-spec detection.

Effect files are the executable behavior contract. They declare concrete required and forbidden effects such as Redis reads, Postgres writes, HTTP calls, queue messages, or forbidden deletes/refunds.

You can use either layer independently:

Existing system tests can produce runtime evidence before feature files exist.
Existing BDD teams can keep feature files and add effect contracts later.
Teams focused on CI gates can start with effect files and reports.
Teams focused on documentation can start by generating feature artifacts.

Artifact Routing

Blackbox can write artifacts to files, stdout, or CI-facing surfaces. The key question is not where every byte goes; it is which outputs are durable review artifacts and which are transient plumbing.

File output is for durable review and later comparison.
Stdout is for quick inspection and scripting.
CI output is for gate signals and annotations.
The same proof can be routed differently without changing what was proven.

Reporter And Sink Defaults

By default, Blackbox enables these reporters:

BLACKBOX_REPORTERS=json,markdown,html,catalog-json,shape-json

JUnit is opt-in:

BLACKBOX_REPORTERS=json,markdown,html,catalog-json,shape-json,junit

By default, Blackbox writes files. In GitHub Actions, the default sink expands to files plus GitHub Actions annotations.

BLACKBOX_SINKS=file
BLACKBOX_SINKS=file,stdout,github-actions

The file sink writes artifacts under the configured artifact directory. For backwards compatibility, BLACKBOX_COVERAGE_OUTPUT can override the path for coverage.json only.

Practical Defaults

Commit testbed config, scenarios, feature files, and effect catalogs when they are part of the durable workflow.
Ignore .blackbox-coverage/ by default.
Archive .blackbox-coverage/ in CI when a failure needs investigation.
Attach omcdc.html and omcdc-propagation.md to CI or PRs when reviewers need branch-level context.
Treat span and V8 files as diagnostic evidence, not hand-edited source.

Figure Placeholder

Caption: The Blackbox artifact map: feature files and effects as durable behavior surfaces; spans, V8 coverage, and reports as generated runtime evidence.

Slot: 