Testing is easier to adopt when the same operation can run from a developer's terminal and from an automated pipeline. If it needs a browser session and a manual export, it gets skipped.
The tooling exposes repeatable audit commands and integration points, so a team can build accessibility checks into its delivery process.
The problem
Audit tools that live only in a dashboard are run before a release, if at all. Developers need a command they can run locally and in continuous integration, with a result a pipeline can act on.
What the system does
- A command contract with consistent options for the target, configuration and output.
- Authentication where the service requires it, and clear errors when it fails.
- Machine-readable output and an exit status a pipeline can use to pass or fail a step.
- Integration packages for using the same checks inside another toolchain.
A representative journey
- Step 1: Install and configureAdd the package and describe the target and options in a config file.
- Step 2: Run a commandRun it locally or as a pipeline step, passing the target and relevant options.
- Step 3: Execute the jobThe tool validates its inputs, calls the underlying audit job and waits for a result.
- Step 4: Return a contractStructured output and an exit status come back, with a distinct code for a tool error.
- Step 5: Keep the evidenceA developer or pipeline stores the report and evidence for the run.
Terminal · illustrative, invented command
$ a11y-audit run --target https://staging.example.test \
--config audit.json --format json
Running 1 job ... done
2 issues (1 serious, 1 moderate)
report: ./audit-report.json
exit code: 1In a delivery pipeline
- Build. Deploy to staging
- Audit. Run the command, store the JSON report
- Decide. Exit 1 = issues found. Exit 2 = tool error.
- Report. Attach the report to the change
Working prototypeUse a small working version of this on invented data, the way a person would.
Try the prototypeInspect the system
This anatomy is a proposed description of how such a system is put together. It is not an audit of a specific deployment.
Inspect the system
How Accessibility audit CLI and packages is put together
- What it is
- CLI inputThe command and its options.
- What flows through it
- A target, options and credentials go in.
- The decision
- A small, consistent set of options across commands.
Read the whole system as a list
- CLI input. The command and its options. Flow: A target, options and credentials go in. Decision: A small, consistent set of options across commands.
- Validated configuration. Checks inputs and prepares a request. Flow: Options and a config file go in. A validated request comes out. Decision: A mistake is reported before any job runs.
- Audit job. The underlying capability that performs the check. Flow: A request goes in. A result and evidence come out. Decision: The package calls the capability. It does not duplicate it.
- Result and error contract. Structured output and an exit status. Flow: A result goes in. JSON and an exit code come out. Decision: Distinct exit codes for issues found and for tool failure.
- Pipeline and report consumption. How a delivery pipeline or developer uses the output. Flow: Output and status go in. A pass, a fail and a stored report come out. Decision: The pipeline decides what is blocking. The tool reports facts.
Key decisions
Stable exit codes
A pipeline needs to tell “the page has issues” from “the tool broke”. Separate exit codes make that decision explicit.
Structured output first
JSON is the contract. A human-friendly summary is a rendering of it, not a second source of truth.
Thin client, shared engine
The package describes what it does itself separately from what the scanning service does, so each can change without breaking the other.
Outcomes and limits
We publish no measured outcomes for this project, because we have none we can evidence. The description above is of what the system does, not of results it has produced.
- No package download count, public registry link, licence or CI integration matrix is claimed.
- The command-line tool does not itself scan. It calls an underlying audit capability.
- Package names and ownership are not given here.
Guardrail
The package reports facts and an exit status. The team's pipeline decides what is blocking.
Technical detail
Technology named in the portfolio for this kind of system. Which parts a given engagement used is not stated.
- Node.js
- TypeScript
- npm
- REST API client
- JSON output