Test Suite Management

The testform suite command provides a dedicated suite of tools for scaffolding, structuring, tag-based filtering, and recording execution outcomes in test runs (.run.feature) and test plans (.plan.feature).

Philosophy: Separation Between State and Execution

Testform is not a test runner and does not compete with test execution engines like Playwright, Cypress, or Vitest:

Test Runners (Playwright, Cypress, Vitest): Responsible for spawning browsers, simulating user interactions, and evaluating assertions in runtime code.
Testform: Manages test infrastructure as code (Test-as-Code), coverage catalogs, the authoritative state ledger (testform.state), and remote reconciliation with Jira or GitHub Projects.

 ┌────────────────────────────────────────────────────────┐
 │  1. DECLARATIVE SUITE GENERATION                       │
 │     testform suite -tags="[@smoke]"                    │
 └──────────────────────────┬─────────────────────────────┘
                            │ (Creates runs/20261024_smoke.run.feature with status=pending)
                            ▼
 ┌────────────────────────────────────────────────────────┐
 │  2. EXTERNAL TEST EXECUTION (Runner)                   │
 │     npx playwright test tests/e2e/                     │
 └──────────────────────────┬─────────────────────────────┘
                            │ (Yields test outcomes: passed / failed)
                            ▼
 ┌────────────────────────────────────────────────────────┐
 │  3. RECORDING RESULTS IN GHERKIN                       │
 │     testform suite mark "@tc-login=passed" -target=... │
 └──────────────────────────┬─────────────────────────────┘
                            │ (Updates "* mark status = passed" lines)
                            ▼
 ┌────────────────────────────────────────────────────────┐
 │  4. REMOTE RECONCILIATION TO GITHUB / JIRA             │
 │     testform apply -auto-approve                       │
 └────────────────────────────────────────────────────────┘

Tag-Based Suite Generation (`suite tags` / `-tags`)

Instantly generate a complete test run (.run.feature) from bracketed tag expressions ([...]):

1. Workspace-Wide Address (`[@tag]`)

Scans all .case.feature files in the workspace and creates a Rule: block for each file containing matching scenarios:

npx testform suite -tags="[@smoke]" -title="Smoke Regression Suite"

Generates the .run.feature artifact:

@testrun @tr-1
Feature: Smoke Regression Suite

  Rule: auth.case.feature
    Scenario: Successful login with valid credentials
      * mark status = pending

  Rule: checkout.case.feature
    Scenario: Credit card payment
      * mark status = pending

2. File-Specific Address (`file.[@tag]`)

Restricts scenario matching to a single .case.feature file:

npx testform suite -tags="checkout.case.feature.[@smoke]"

3. Multiple Tags

Supports comma-separated tags within brackets. Scenarios matching any of the specified tags are included:

npx testform suite -tags="[@smoke,@critical]"

Standardized `testform suite` Subcommands

The command features 5 standardized subcommands:

Subcommand	Description	Syntax
`tags`	Generates a `.run.feature` suite filtered by bracketed tag expressions.	`testform suite tags "<address>"` or `testform suite -tags="<address>"`
`init`	Scaffolds the skeleton of a `.run.feature` or `.plan.feature` file.	`testform suite init -scope=<testrun\|testplan> [-title=<title>]`
`fill`	Autocompletes empty `Rule` blocks in a testrun with their source `.case.feature` scenarios.	`testform suite fill -target=<target>`
`link`	Links a testcase or testrun into a target suite.	`testform suite link "<identifier>=<status>" -target=<target>`
`mark`	Updates execution outcomes (`* mark status = <status>`) inside a testrun.	`testform suite mark "<identifier>=<status>" -target=<target>`

Unified Identification Strategies

All testform suite subcommands use consistent resolution strategies:

Target Strategy (`-target=<target>`)

Used by fill, link, and mark to identify the destination suite:

Canonical Address: tests/runs/smoke.run.feature.@tr-1 (or smoke.run.feature.@tr-1)
File Path: tests/runs/smoke.run.feature (or relative path)
Identity Tag: @tr-1

Identifier Strategy (`<identifier>=<status>`)

Used by mark and link to identify a specific test scenario:

Identity Tag: "@tc-1=passed"
Canonical / File: "checkout.case.feature.@tc-1=passed"
Scenario Name: "Credit card payment=passed"

Supported statuses: pending, passed, failed, blocked, skipped, undefined.

CI/CD Pipeline Integration

Connect your automated runner with Testform inside GitHub Actions or GitLab CI:

- name: Generate Smoke Testrun
  run: npx testform suite -tags="[@smoke]" -title="CI PR #${{ github.event.number }}"

- name: Execute Automated Tests
  id: runner
  run: npx playwright test --reporter=json > test-results.json

- name: Record Outcomes in Testform Suite
  run: |
    # Script parsing test-results.json to update Testform
    npx testform suite mark "@tc-auth-001=passed" -target="@tr-1"
    npx testform suite mark "@tc-checkout-001=failed" -target="@tr-1"

- name: Reconcile Remote State with GitHub Projects
  run: npx testform apply -auto-approve

Test Suite Management

Philosophy: Separation Between State and Execution

Tag-Based Suite Generation (suite tags / -tags)

1. Workspace-Wide Address ([@tag])

2. File-Specific Address (file.[@tag])