Skip to content

Extending Attest ​

CDX owns shared surfaces, runner adapters, validators, gates and report engines. Consumer repositories own their plans, datasets, registrations and product scenarios. Paths such as config/ below are relative to a consumer's Attest product root. The product plan defines current delivery scope; this guide explains extension ownership.

Add a plan ​

  1. Add a typed JSON plan under config/plans/.
  2. Reference one dataset profile from config/datasets/.
  3. Define suites, tests, checkpoints, mandatory scope, gate policy, and report template in that plan.
  4. Register the executable suite in registry/modules/ and manifests/.
  5. Add contract, gate, integrity, and runner tests.

Do not duplicate plan metadata in the test, dashboard, or PDF renderer.

Add checkpoints and evidence ​

Each UI checkpoint requires:

  • stable checkpoint ID
  • immutable execution-local evidence ID such as EV-014
  • title and expected behavior
  • actor
  • mandatory flag
  • verification categories
  • evidence requirement

The Patrol helper records observed behavior and capture time. The internal collector preserves and hashes the screenshot; the immutable evidence context is carried by the manifest and report. Generic renderers do not contain test-specific names.

Add a test surface ​

  1. Add or reuse a QualificationSurface and QualificationReportTemplate.
  2. Register its applicable report sections in qualification_report_template.dart.
  3. Implement a runner adapter that returns canonical suite, test, checkpoint, assertion, and evidence data.
  4. Add only meaningful surface metrics.
  5. Test missing, corrupt, failed, blocked, skipped, and clean-success paths.

Use the existing API, action/integration, UI and performance surfaces where they fit. A report mapping alone does not implement a runner or evidence collector; advertise a surface only after execution and evidence are verified.

Dataset profiles ​

A dataset profile owns ID, version, seed version, initialization strategy, isolation mode, baseline count, generated count/prefix, and optional checksum. Reset and initialization must finish before the dataset gate can pass.

Gate changes ​

Gate policy belongs in plan configuration. Gate evaluation belongs in qualification_gate_evaluator.dart. The dashboard and report may display gate output but must never calculate it independently.