Configure Providers

Providers in Testform are decoupled modular plugins that connect declarative BDD test specifications with quality management and state platforms (GitHub Issues / Projects, GitLab, Jira, or Local Ledger).

Just as in Terraform a provider manages communication with cloud APIs (AWS, Azure, GCP) to record infrastructure state, in Testform a provider manages communication with the issue tracker or state storage to create, update, close, and version test cases and execution runs as code in Git.

Caution

Key Difference: Providers vs Test Runners

• Provider (provider): Traceability and management platform hosting test cases and the state ledger (local, github, gitlab, jira).
• Test Runner: Automation tool that executes test code in browsers, APIs, or sockets (Playwright, Cypress, Supertest, K6).

---

Declaration in main.yml

Providers are configured in the root main.yml file:

main.yml

testform:
  required_version: ">= 1.0.0"
  backend:
    local:
      path: "./testform.state"

provider:
  github:
    owner: "my-organization"
    repository: "my-web-platform"
    token_env: "GITHUB_TOKEN"
  jira:
    host: "my-company.atlassian.net"
    project_key: "QA"
    email: "qa-team@company.com"

---

Available Providers

Provider	Storage Type	Recommended Usage
local	Local testform.state file	Agile projects, local suites, and offline Git repositories with no external dependencies.
github	GitHub Issues + GitHub Projects (GraphQL)	Teams centralizing specifications and test tracking in GitHub Enterprise / Cloud.
gitlab	GitLab Issues + Scoped Labels	GitLab CI/CD pipelines tracking tests on GitLab issue boards.
Custom Providers	Registered via registerResource()	Custom integrations with proprietary QA platforms, TestRail, or Xray.

---

GitHub Provider Detailed Setup (provider: github)

When using GitHub as your test management platform, Testform interfaces with the GraphQL API of GitHub Projects (Projects V2) and the REST API of GitHub Issues. To guarantee seamless two-way synchronization, your target repository and organization must meet the following configuration requirements:

1. GitHub Projects (Projects V2) Board

• An active GitHub Projects V2 board (at organization or user level) linked to the target repository.
• The project board must contain a Single-select field named strictly Status.
• The Status field must contain the following exact option values:
  • Todo
  • Done
  • passed
  • failed
  • blocked
  • skipped
  • unexecuted

2. Required Labels

Testform maps declarative resources (testcase, testrun, testplan, etc.) to issue labels. The following 5 labels are mandatory:

• bug
• testcase
• testplan
• testreport
• testrun

3. Authentication & Token Permissions (PAT)

The authentication token configured via token_env or testform login must have the appropriate scopes:

• Classic Personal Access Token (PAT):
  • Scope repo (Full control of private and public repositories).
  • Scope project (Read and write GitHub projects).
• Fine-Grained Personal Access Token:
  • Repository permission: Issues set to Read and write.
  • Organization permission: Projects set to Read and write.

Rapid Automated Setup

You can provision all required labels, the GitHub Projects V2 board, and synchronization workflows in seconds by triggering the official Install Testform Labels and Project action in your repository.

---

Provider Initialization (testform init)

Before running a plan, testform init validates credentials and sets up the workspace:

testform init

During initialization:

1. Verifies access tokens (e.g. GITHUB_TOKEN or GITLAB_TOKEN).
2. Configures the state backend and creates the state lock file (.lock).
3. Verifies repository access and project boards.