Installation and Quickstart

Learn how to install Testform globally, initialize your workspace, and understand state persistence lifecycle across local and cloud backends.

Prerequisites

1. Base Runtime Environment

Before getting started, ensure your environment has:

• Node.js: version 18.0.0 or higher installed (node -v).
• Git: an active Git repository initialized in your workspace (git status).
• NPM: package manager to install the global Testform binary (npm -v).

2. Operational Modes and Providers

Testform supports two primary operational modes depending on your team’s workflow:

Local / Offline Mode (provider: local)

When configuring provider: local and backend: local, no external accounts, tokens, or network connectivity are required. Testform operates 100% offline out-of-the-box, storing your test management ledger locally in testform.state or directly committed to Git.

GitHub Provider Mode (provider: github)

When integrating Testform with GitHub to synchronize test cases, execution runs, and suites into GitHub Issues and GitHub Projects, your repository and organization must meet the following prerequisites:

1. GitHub Project (Projects V2):

   • An active GitHub Project (organization or user level) linked to your target test repository.
   • A single-select field named strictly Status, configured with the following exact option values:
     • Todo
     • Done
     • passed
     • failed
     • blocked
     • skipped
     • unexecuted

2. Repository Labels:

   • The target repository requires the following 5 labels to categorize and track issues:
     • bug
     • testcase
     • testplan
     • testreport
     • testrun

3. Authentication & Token Permissions:

   • A Personal Access Token (PAT) configured with:
     • Classic PAT: repo (Full control of private repositories) and project (Read and write projects) scopes.
     • Fine-Grained PAT: Repository permissions (Issues: Read and write) and Organization permissions (Projects: Read and write).
   • Exported as an environment variable (e.g. export GITHUB_TOKEN="ghp_...") or configured via testform login.

   Note

   GitHub Actions Recommendation: The default GITHUB_TOKEN provided by Actions lacks the necessary permissions to manipulate organization-level GitHub Projects (V2). In automated CI/CD pipelines, configure a dedicated repository secret with a custom PAT (e.g., secrets.TESTFORM_GITHUB_TOKEN) so test runs can transition issue states and sync project boards.

4. Automated Setup Workflow (Recommended): To automate the setup of labels and project board in seconds, we recommend using the official Install Testform Labels and Project workflow (.github/workflows/install.yml). It automatically:

   • Creates the 5 required labels (bug, testcase, testplan, testreport, testrun).
   • Clones the official Testform Template Project into your account or organization and links it to your repository.
   • Configures the Status single-select field with all QA options and status colors.
   • Installs the close-issue.yml workflow to automate issue closing and state transitions.

3. Optional Binary Report Drivers (Word & Excel)

To maintain an ultra-compact binary footprint (~1 MB), binary document generators (docx and exceljs) are decoupled as optional peer dependencies. If you plan to generate Word (.docx) or Excel (.xlsx) execution reports, install them on demand:

npm install -g docx exceljs
# Or locally in your project:
npm install --save-dev docx exceljs

Step 1: Global Installation

Testform is a command-line interface (CLI) tool designed to be installed strictly globally on your operating system, just like Terraform or Git:

npm install -g @fromeroc9/testform@beta

Verify your installation by printing the binary version:

testform -version

Expected terminal output:

Testform v1.1.0
on win32_x64

Testform automatically queries the NPM registry to verify if an update is available. If your CLI is out of date, it prints an alert similar to Terraform:

Your version of Testform is out of date! The latest version
is 1.18.0. You can update by running:
  npm install -g @fromeroc9/testform@beta

Step 2: Initialize Workspace (testform init)

Run the testform init command in the root of your project:

testform init

Actual terminal output:

Initializing the backend...
Initializing Testform configuration...
- Configuration: main.yml (v1.0)
- State backend: ready

Testform has been successfully initialized!

You may now begin working with Testform. Try running "testform plan" to see
any changes that are required for your test management resources.

If you ever set or change configuration for Testform, rerun this command to
reinitialize your working directory.

Step 3: Generated Structure and State Lifecycle

Following Terraform’s architecture, testform init generates only the configuration manifest. It does not create premature state files or hidden control folders.

my-project/
└── main.yml            # Primary workspace configuration manifest

Lifecycle in Local Backend (backend: local)

When using the default local backend, state files are created dynamically as you progress through the workflow:

1. After testform init:
   • Only main.yml exists. Neither testform.state nor backup files are created.
2. During testform plan:
   • If testform.state does not yet exist on disk, Testform evaluates an in-memory empty state (0 resources) and calculates planned additions (+ create) in read-only mode, without touching disk.
3. After the first testform apply:
   • When resources are reconciled successfully, testform.state is created for the first time with serial: 1 and the reconciled resource attributes. No .backup file is created since there was no previous state.
4. From the second testform apply onwards:
   • Before mutating state, Testform backs up the previous state to testform.state.backup (serial: 1) and writes the new state to testform.state (serial: 2). Both files share the exact same JSON format.

my-project/
├── main.yml            # Primary workspace configuration manifest
├── testform.state          # Active state (created after first apply)
└── testform.state.backup   # Automatic snapshot backup (created from second apply onwards)

Lifecycle in Remote Cloud Backends (s3, oci, azurerm, gcs)

When configuring a remote cloud backend in main.yml:

my-project/
└── main.yml            # Primary workspace configuration manifest

• No local state files: At no point are testform.state or testform.state.backup written to your local disk.
• Direct Cloud Persistence: Read and write mutations (s3.putObject, UploadBlob, etc.) stream directly and atomically to the remote bucket.
• Clean Git Repository: Keeps your local workspace 100% free from state files, preventing Pull Request merge conflicts and accidental credential leaks.
• Native Cloud Resiliency: Disaster recovery and revision history are managed via the cloud provider’s native Object Versioning (Bucket Versioning).