Alexandria
API & Development

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.

MakeTaskWhat it does
make buildtask buildBuilds the five binaries into bin/.
make build-guitask build:guiBuilds the console and embeds it in the server and the client (-tags gui).
make fmttask fmtgofumpt -w .
make linttask lintgolangci-lint run
make testtask testAll tests with the race detector and a coverage profile.
make covertask coverOpens the coverage report.
make conformancetask conformanceThe conformance battery.
make e2etask e2eThe end-to-end F6 scenario.
make demotask demoThe F6 demo table.
make tracetask traceRegenerates and verifies the traceability matrix.
make check—fmt, lint, test, conformance, trace.
make vulntask vulngovulncheck.
make gui-devtask gui:devConsole development server.
make docs-devtask docs:devDocumentation development server.
make tutorialtask tutorialJupyterLab 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/clock may 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:

JobSteps
checkgo mod tidy leaves no diff · gofumpt -l . is empty · go vet ./... · golangci-lint run · go test -race ./... · go run ./conformance/trace · govulncheck.
buildmake build.

.github/workflows/deploy-docs.yaml builds this site and publishes it to GitHub Pages.

On this page