Declarative Resources

Testform defines four fundamental declarative resource primitives to model your end-to-end quality engineering strategy: testcase, testrun, testplan, and testsuite.

1. The testcase Resource

The testcase resource represents an isolated test specification. In Testform, each Scenario inside a .case.feature file represents an independent test case.

• Standard Location: tests/features/*.case.feature
• Identity Tag Placement: Directly above the Scenario: with @tc-* prefix (e.g. @tc-cancel-001 or @tc-cancel-order).
• Uniqueness Scope: Unique within that .case.feature file. Resolved as path/to/file.case.feature.@tc-cancel-001.
• Lifecycle: draft -> active -> deprecated -> archived

Multi-Testcase Feature File Example

Feature: Cancel Pending Purchase Orders
  As a customer with a pending shipment order
  I want to cancel my purchase order from the dashboard
  In order to receive an immediate refund

  Background:
    * field automate = apply

  @high @tc-cancel-001
  Scenario: Cancellation before product fulfillment
    Given order "ORD-9912" is in "Pending" status
    When the customer clicks "Cancel Order"
    And confirms reason "Changed mind"
    Then the order status updates to "Cancelled"
    And a full refund request is submitted

  @medium @tc-cancel-002
  Scenario: Cancellation attempt on already shipped order
    Given order "ORD-8810" is in "Shipped" status
    When the customer clicks "Cancel Order"
    Then the system displays warning "Shipped orders cannot be cancelled"

2. The testrun Resource

The testrun resource captures an immutable historical execution of a test set against a specific build or commit.

• Standard Location: tests/runs/*.run.feature
• Identity Tag Placement: Above the Feature: with @tr-* prefix (e.g. @tr-regression-build-412). 1 .run.feature file = 1 complete execution run.
• Uniqueness Scope: Globally unique across the entire repository.
• Internal Structure: Uses Rule: blocks targeting .case.feature files and Scenario: selectors matching included test cases.

Example

@tr-regression-build-412 @high
Feature: Regression Test Run Build 412
  Timestamp: 2026-10-21T14:30:00Z
  Triggered By: GitHub Actions (#8912)

  Background:
    * field description = "Critical purchase flow validation"

  Rule: orders.case.feature

  Scenario: @tc-cancel-001
    * mark status = passed

  Rule: auth.case.feature

  Scenario: @tc-login-001
    * mark status = failed

Rollup Verdict Engine

Testform automatically determines the overall execution outcome (status) of each testrun by evaluating all individual child test cases (testcases). This calculation adheres to strict QA precedence rules:

1. failed (High Precedence): If at least one testcase has failed, the entire testrun is deemed failed.
2. pending (Medium Precedence): If no testcase failed, but at least one testcase remains pending, blocked, or skipped (or if the suite contains zero cases), the status is pending.
3. passed (Complete Consensus): Conferred only when 100% of child test cases have succeeded with status passed.

Compact Ledger Representation (testform.state)

To minimize state file footprint and ensure universal compatibility across providers (Local, GitHub, Jira, GitLab), testrun resources persist their executions as a clean, lightweight key-value dictionary:

{
  "address": "tests/runs/regression.run.feature.@tr-regression-build-412",
  "type": "github_testrun",
  "status": "failed",
  "attributes": {
    "title": "Regression Test Run Build 412",
    "status": "failed",
    "testcases": {
      "tests/features/orders.case.feature.@tc-cancel-001": "passed",
      "tests/features/auth.case.feature.@tc-login-001": "failed"
    },
    "metadata": {}
  }
}

• testcases: Compact key-value mapping of { [case_canonical_address]: status }.
• metadata: Extensible object reserved for providers to record auxiliary execution metadata (build IDs, CI links) without polluting core state.
• Zero Comment Spam: Legacy per-testcase issue comments have been replaced by a dynamic, interactive checklist inside the main Issue body, eliminating notification noise and boosting CLI performance.

3. The testplan Resource

The testplan resource models certification matrices, coverage thresholds, and milestone release readiness.

• Standard Location: tests/plans/*.plan.feature
• Identity Tag Placement: Above the Feature: with @tp-* prefix (e.g. @tp-release-v250). 1 .plan.feature file = 1 complete certification plan.
• Uniqueness Scope: Globally unique across the entire repository.
• Internal Structure: Uses Rule: blocks binding referenced runs (*.run.feature). Must not contain explicit Scenario blocks.

Example

@tp-release-v250 @high
Feature: Release v2.5.0 Certification Matrix
  Objective: Validate authentication and billing flows prior to production deployment.

  Background:
    * field description = "Release v2.5.0 QA Sign-off"

  Rule: smoke.run.feature

  Rule: regression.run.feature

Hierarchical Certification Verdict

Just as a testrun evaluates its test cases, a testplan calculates its overall status by hierarchically aggregating the rollup statuses of all linked testrun suites:

• If any referenced testrun is failed, the testplan verdict is failed.
• If no run is failed but any run is still pending, the plan remains pending.
• Only when all referenced testrun suites reach passed, the testplan transitions to passed.

State Ledger Representation (testform.state)

{
  "address": "tests/plans/release.plan.feature.@tp-release-v250",
  "type": "github_testplan",
  "status": "failed",
  "attributes": {
    "title": "Release v2.5.0 Certification Matrix",
    "status": "failed",
    "testruns": {
      "tests/runs/smoke.run.feature.@tr-smoke-412": "passed",
      "tests/runs/regression.run.feature.@tr-regression-build-412": "failed"
    },
    "metadata": {}
  }
}

4. The testsuite Resource

The testsuite resource dynamically groups test cases based on boolean tag queries (@smoke, @billing) for execution and orchestration with automated test runners (Playwright, Cypress, Vitest).

Resource Comparison Matrix

Resource	File Scope	Identity Tag Placement	Uniqueness	Internal Structure
testcase	1 file = N test cases	Above each Scenario:	Unique within file	Isolated Scenario blocks with Given, When, Then
testrun	1 file = 1 test run	Above the Feature:	Global across repo	Rule: file.case.feature + Scenario: @tc-*
testplan	1 file = 1 test plan	Above the Feature:	Global across repo	Rule: file.run.feature (no explicit Scenarios)
testsuite	Logical grouping	In-memory / runtime	Dynamic query	Evaluates scenarios matching boolean tag filter

---

Custom Resources

Beyond native resources (github_testcase, github_testrun, github_testplan), Testform allows defining custom resource templates to map Gherkin scenarios to external APIs (Jira, Zephyr, Azure DevOps, or proprietary QA backends).

Auto-Discovery by Convention

Testform automatically scans and registers template definitions from:

• .testform/resources/*.js (or ./resources/*.js).
• Shared modules: .testform/modules/**/resources/*.js.

Custom Resource Template Example

.testform/resources/jira-testcase.js

module.exports = {
  type: 'jira_testcase',
  fields: [
    { name: 'summary', value: (scenario) => scenario.name },
    { name: 'description', value: (scenario) => scenario.description || '' },
    { name: 'priority', value: (scenario) => scenario.custom?.fields?.priority || 'Medium' }
  ],
  comments: (scenario, context) => [
    {
      identity: scenario.custom?.identity,
      status: scenario.custom?.fields?.status || 'passed',
      body: `Automated execution report (build #${context?.buildId || 'local'})`,
      title: scenario.name
    }
  ]
};