Requirements and Supported Stacks
List the runtime, OpenTelemetry, Playwright, Docker, and project assumptions before the first run.
Abstract
This page is the gate before the first proof run. It explains what Blackbox needs from your system-test environment before it can collect runtime evidence and produce coverage artifacts.
Audience
Developers who want to know whether Blackbox can run in their repo right now.
Supported Alpha Stack
The current alpha path is aimed at Node services that can be started as containers and driven by Playwright system tests.
| Requirement | Why Blackbox needs it |
|---|---|
| Node services | The current bootstrap instruments Node processes by loading a Blackbox OpenTelemetry bootstrap before app code starts. |
| Docker or Docker Compose | Blackbox layers a generated test overlay on top of your runnable topology. |
| Playwright system tests | Playwright drives the workflow while Blackbox collects the runtime evidence caused by that workflow. |
| A service image with a shell | The current node wrapper is a POSIX shell script. Distroless images need a different wrapper and are a known limitation. |
| A normal service command | Blackbox expects your service to start through node, for example CMD ["node", "src/server.js"]. |
| Managed local dependencies | Databases, queues, caches, and local services should be owned by the test topology when possible. |
Remote end-to-end environments can still be valuable, but they usually include unmanaged dependencies such as auth providers, email systems, payment providers, shared queues, or vendor APIs. Blackbox is strongest as a behavioral gate when the system under test and its dependencies are controlled enough for a failure to mean something specific.
What Blackbox Does Not Require
You do not need to add OpenTelemetry code to production services. You also do not need to create a second test-only Dockerfile for each service in the default path.
At test time, Blackbox uses an OpenTelemetry bootstrap image, a generated Docker Compose overlay, and a node wrapper mounted into the SUT container. The production-shaped service image remains the image being tested.
What Must Be True Before You Continue
- You can build and start the app or service under test.
- You can run at least one system test that reaches a real boundary.
- Your service starts through a Node binary path Blackbox can shadow.
- Docker can start the topology locally or in CI.
- You know which dependencies are managed by the test run and which are external.
- You have a writable artifact directory for reports such as
.blackbox-coverage/.
Known Alpha Limits
- The current bootstrap path is Node-focused.
- Distroless service images are not the happy path because the wrapper needs a shell.
- Services with existing tracing agents such as Datadog or Sentry may need test-environment overrides.
- Remote E2E environments with unmanaged dependencies can produce noisy failures and should not be the first proof run.