ACG-TEST

The Standard

This standard defines a human-readable YAML format for testing GitHub Actions workflows before they exist. Tests are written first, watched fail, then the workflow is written until the tests pass.

1. Purpose

The architecture nests using the Konomi Standard UDT pattern: each type is self-contained, composable, and inherits from a shared base.

2. Base Types

UDT:Expectation

The atomic unit. Every check in the system resolves to one expectation.

UDT:Expectation:
  fields:
    expect:
      type: enum
      values: [present, triggered, not triggered, configured]
    reason:
      type: string
      required: true
      purpose: "plain English explanation"
    result:
      type: enum
      values: [pass, fail, skip]
      default: skip

UDT:PathPattern

A file path with a glob pattern used to match triggers.

UDT:PathPattern:
  fields:
    path:
      type: string
      format: glob

UDT:Secret

A named secret the workflow depends on.

UDT:Secret:
  inherits: UDT:Expectation
  fields:
    name: string
    expect: [configured]

3. Trigger Types

UDT:EventTrigger defines which GitHub event should or should not activate the workflow. UDT:PathWatch tests whether a specific file change would or would not trigger it.

4. Notification Type

UDT:Notification defines the expected shape of the outbound notification: type, recipient, sender, subject, body. Each nested field inherits from UDT:Expectation.

5. Guardrail Type

UDT:Guardrail defines conditions under which the workflow must NOT fire. Constrained to expect: not triggered.

6. Test Type (the root)

UDT:WorkflowTest is the top-level type. One per workflow. Contains exists, triggers, watches, notification, secrets, guardrails.

7. Inheritance diagram

UDT:Expectation          ← base of everything
├── UDT:EventTrigger     ← what events fire the workflow
├── UDT:PathWatch        ← what file changes trigger it
├── UDT:Guardrail        ← what must NOT trigger it
├── UDT:Secret           ← what config must exist
└── UDT:Notification     ← what gets sent
    ├── .recipient       ← who receives
    ├── .sender          ← who sends
    ├── .subject         ← what the subject contains
    └── .body            ← what the body contains

UDT:WorkflowTest         ← root container
├── .exists              → UDT:Expectation
├── .triggers[]          → UDT:EventTrigger
├── .watches[]           → UDT:PathWatch
├── .notification        → UDT:Notification
├── .secrets[]           → UDT:Secret
└── .guardrails[]        → UDT:Guardrail

10. Runner commands

acg-test run <file>              run one test file
acg-test run tests/              run all tests in folder
acg-test init <workflow-name>    scaffold a blank test file
acg-test validate <file>         check test YAML structure only
acg-test report                  summary of all tests across repo

11. File layout

repo/
├── .github/workflows/article-notification.yml
├── tests/article-notification.test.yml
└── acg-test.config.yml

12. Design rules

  1. Every expectation has a reason.
  2. Four words only in expect.
  3. Three results only in result.
  4. Tests before code.
  5. UDT inheritance — every type traces back to UDT:Expectation.
  6. One test file, one workflow.

Page verification

The tests for this page live in tests/standard.test.yml.

Loading…