Testing & CI
Build and test targets, test conventions, architecture tests and the GitHub Actions pipeline of Alexandria.
Testing & CI
1. Targets
Makefile and Taskfile.yaml expose the same workflow.
| Make | Task | What it does |
|---|---|---|
make build | task build | Builds the five binaries into bin/. |
make build-gui | task build:gui | Builds the console and embeds it in the server and the client (-tags gui). |
make fmt | task fmt | gofumpt -w . |
make lint | task lint | golangci-lint run |
make test | task test | All tests with the race detector and a coverage profile. |
make cover | task cover | Opens the coverage report. |
make conformance | task conformance | The conformance battery. |
make e2e | task e2e | The end-to-end F6 scenario. |
make demo | task demo | The F6 demo table. |
make trace | task trace | Regenerates and verifies the traceability matrix. |
make check | — | fmt, lint, test, conformance, trace. |
make vuln | task vuln | govulncheck. |
make gui-dev | task gui:dev | Console development server. |
make docs-dev | task docs:dev | Documentation development server. |
make tutorial | task tutorial | JupyterLab with the notebooks. |
2. Test Conventions
- Granular tests. One behaviour per test; fixtures, stubs and helpers sit at the top of the file, each with a one-line comment.
- Requirement tests are named
TestT_<AREA>_<NNN>_<Behaviour>and are picked up by the traceability generator. - Negative cases are named after their code (
N-<CODE>). - No wall clock. Tests inject a clock; only
internal/clockmay read the system time. - In-process doubles from
internal/testkit(in-memory stores, a fake identity provider, a fake upstream) let most tests run without processes or ports. - Comments. Every file starts with a two-line header; every function and type has one line.
The default build has no console: tests and CI need only Go. internal/webui is tested against an in-memory build, and a separate test checks that nothing is mounted without the gui tag.
3. Architecture Tests
internal/archtest fails the build when a dependency rule is broken: layers pointing outward, the two contexts importing each other, a module outside the DP-1 allow-list, a wall-clock read outside internal/clock, or a capability appearing on the hot path. See the architecture overview.
4. Continuous Integration
.github/workflows/ci.yaml runs on pushes to main and on pull requests:
| Job | Steps |
|---|---|
check | go mod tidy leaves no diff · gofumpt -l . is empty · go vet ./... · golangci-lint run · go test -race ./... · go run ./conformance/trace · govulncheck. |
build | make build. |
.github/workflows/deploy-docs.yaml builds this site and publishes it to GitHub Pages.
Conformance & Traceability
How Alexandria proves the 81 requirements and 76 of the 77 catalog codes of specification v0.3.0, replays scenario F6 and generates the traceability matrix.
Decisions
Architecture Decision Records of Alexandria, the current Vocabulary Hub v0.3.0 decisions and the historical records of the removed identity prototype.