State Ledger & Management

The State (testform.state) is the authoritative ledger mapping your declarative test specifications to the physical execution reality and attributes of each test run.

Just as Terraform’s state file tracks IDs of created cloud instances, Testform’s state records test execution identifiers, content hashes for drift detection, pass/fail status, and generated outputs.

---

State Ledger File (testform.state)

The state is a structured JSON ledger maintained after every testform apply. It records canonical reconciliation across testcase, testrun, and testplan resources:

{
  "version": "1.0.0",
  "testform_version": "1.1.0",
  "serial": 12,
  "lineage": "c8f2b1a9-45e1-...",
  "resources": [
    {
      "address": "tests/features/cart.case.feature.@tc-01",
      "type": "github_testcase",
      "name": "tc-01",
      "status": "passed",
      "hash": "a1b2c3d4...",
      "attributes": {
        "title": "Add item to cart",
        "issueNumber": 401
      }
    },
    {
      "address": "tests/runs/checkout.run.feature.@tr-01",
      "type": "github_testrun",
      "name": "tr-01",
      "status": "failed",
      "attributes": {
        "title": "Checkout Regression Run",
        "status": "failed",
        "testcases": {
          "tests/features/cart.case.feature.@tc-01": "passed",
          "tests/features/cart.case.feature.@tc-02": "failed"
        },
        "metadata": {}
      }
    },
    {
      "address": "tests/plans/sprint42.plan.feature.@tp-01",
      "type": "github_testplan",
      "name": "tp-01",
      "status": "failed",
      "attributes": {
        "title": "Sprint 42 Certification Plan",
        "status": "failed",
        "testruns": {
          "tests/runs/checkout.run.feature.@tr-01": "failed"
        },
        "metadata": {}
      }
    }
  ],
  "outputs": {
    "login_title": {
      "value": "Successful user login",
      "type": "string"
    }
  }
}

Key Resource Attributes in State

Field	Resource(s)	Description
status	testcase, testrun, testplan	Execution outcome or consolidated Rollup Verdict.
testcases	testrun	Key-value dictionary { [case_identity]: status } of all executed test cases.
testruns	testplan	Key-value dictionary { [run_identity]: status } of all test runs included in the plan.
metadata	testrun, testplan	Extensible object for provider-specific attributes (build numbers, CI links, remote IDs).

---

Distributed State Locking (testform.state.lock)

To prevent race conditions and state corruption when multiple engineers or parallel CI/CD runners access the same repository, Testform enforces atomic state locking:

1. Before starting a plan or execution, Testform acquires an exclusive lock (testform.state.lock).
2. The lock records process ID (PID), user, hostname, and timestamp.
3. If another process attempts to access the locked state:

[ERROR] Error acquiring the state lock:
  Lock Info:
    ID:        a9b8c7-lock
    Path:      testform.state
    Operation: OperationTypeApply
    Who:       runner-1@ci-node-4
    Created:   2026-10-24 17:15:00 UTC

---

Drift Detection

During reconciliation (testform refresh or testform plan):

• Testform evaluates cryptographic checksums of each scenario’s source steps.
• If physical execution results or local code have drifted from the state ledger, an update diff (~ update) is planned.
• Silent regressions or modified assertions are surfaced immediately before execution.