Test-as-Code Architecture and Principles

Explore the core architectural principles powering Testform and the Test-as-Code (TaC) paradigm.

Why Test-as-Code?

Historically, software test management has been isolated from modern engineering workflows:

• Information Silos: Test cases are manually documented in heavy external web UIs (Jira, Zephyr, TestRail) or stale spreadsheets.
• Lack of Provenance: Changes in test specifications are not linked to Git commits or reviewed during Pull Requests.
• Drift and Staleness: Production code moves faster than manual documentation, leading to technical debt and broken test suites.

Test-as-Code translates the principles that revolutionized modern infrastructure (Terraform, Kubernetes, Ansible) to Quality Engineering:

1. Git Versioning: Test cases live alongside application source code in the same repository and evolve within the same PRs.
2. Declarative Paradigm: Engineers specify the desired state in Gherkin files; the reconciliation engine calculates the operations required to match it.
3. Idempotency: Executing testform apply once or ten times produces the exact same end state across remote systems.
4. Cryptographic State Ledger: An immutable state file stores SHA-256 hashes of every declared resource to detect out-of-band drift automatically.

The Three-State Model

+-------------------------------------------------------------+
| 1. Desired State (Git)                                      |
|    tests/features/*.case.feature                             |
|    Authored by engineers using standard Gherkin directives  |
+------------------------------+------------------------------+
                               |
                               v
+-------------------------------------------------------------+
| 2. Known State (Ledger)                                     |
|    testform.state (Local / OCI / S3 / Azure / GCS)          |
|    Immutable registry of resource identities, metadata, sha |
+------------------------------+------------------------------+
                               |
                               v
+-------------------------------------------------------------+
| 3. Actual State (Providers)                                 |
|    GitHub Projects V2 / GitLab / Jira API                   |
|    Live remote entities reconciled during each diff cycle   |
+-------------------------------------------------------------+

The State Ledger (testform.state)

The state ledger is a JSON document serving as the single source of truth for Testform. It includes:

{
  "version": 4,
  "testform_version": "1.0.0",
  "serial": 12,
  "lineage": "a8b3c4d5-e6f7-4890-bcde-1234567890ab",
  "resources": [
    {
      "scope": "testcase",
      "id": "@tc-auth-001",
      "provider": "github",
      "remote_id": "I_kwDOB12345",
      "hash": "7f83b1657ff1fc53b92dc18148a1d65dfc2d4b1fa3d677284addd200126d9069",
      "attributes": {
        "title": "Successful login with valid email and password",
        "feature": "User Authentication",
        "priority": "High",
        "component": "auth",
        "status": "draft"
      }
    }
  ]
}

• Serial: Monotonically increasing counter safeguarding against concurrent or out-of-order writes.
• Lineage: Unique UUID representing the persistent identity of the workspace.
• SHA-256 Hash: Content checksum enabling instant diff detection without premature remote API calls.