@fromeroc9/testform 1.0.17 → 1.1.0-beta.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,90 +1,198 @@
1
- # Testform
1
+ <p align="center">
2
+ <img src="assets/logo.svg" alt="Testform Logo" width="80" height="80" />
3
+ </p>
2
4
 
3
- **Testform** brings the **Test-as-Code** paradigm to your version control platforms. It transforms standard issue trackers (like GitHub) into full-fledged Test Management ecosystems. By treating your QA processes as code, it codifies issue APIs into declarative Gherkin (`.feature`) configurations that can be shared amongst team members, edited, reviewed in Pull Requests, and strictly versioned.
5
+ <h1 align="center">Testform</h1>
6
+
7
+ <p align="center">
8
+ <strong>Declare, plan, apply, and reconcile in Git.</strong>
9
+ </p>
10
+
11
+ <p align="center">
12
+ <a href="https://www.npmjs.com/package/@fromeroc9/testform"><img src="https://img.shields.io/npm/v/@fromeroc9/testform/beta?style=flat-square&color=4F46E5&label=npm%20beta" alt="NPM Beta Version" /></a>
13
+ <a href="https://fromeroc9.github.io/testform-docs/"><img src="https://img.shields.io/badge/docs-online-4F46E5?style=flat-square&logo=gitbook&logoColor=white" alt="Docs Online" /></a>
14
+ <a href="https://nodejs.org/"><img src="https://img.shields.io/badge/node-%3E%3D%2018.0.0-339933?style=flat-square&logo=node.js&logoColor=white" alt="Node.js Version" /></a>
15
+ <img src="https://img.shields.io/badge/tests-43%20passed%20%7C%20356%20units-brightgreen?style=flat-square&logo=vitest&logoColor=white" alt="Test Status" />
16
+ <a href="https://github.com/fromeroc9/testform-docs"><img src="https://img.shields.io/badge/portal-testform--docs-0284C7?style=flat-square&logo=astro&logoColor=white" alt="Docs Portal" /></a>
17
+ <a href="LICENSE"><img src="https://img.shields.io/badge/license-GPL--3.0-blue?style=flat-square" alt="License" /></a>
18
+ </p>
4
19
 
5
20
  ---
6
21
 
7
- ## 📚 Documentation
22
+ **Testform** is a **declarative test framework** built on the **Test-as-Code (TaC)** paradigm with **zero mandatory SaaS servers and zero Test Drift**. It transforms your Git repository into an immutable, cryptographic QA ledger. Manage your entire testing lifecycle, declare test specifications as versioned Gherkin (`.feature`) code, plan speculative diffs, reconcile execution states across platforms, and review quality gates directly in Pull Requests.
23
+
24
+ ---
8
25
 
9
- We have completely overhauled our documentation to be as intuitive and comprehensive as possible.
26
+ ## 📚 Documentation
10
27
 
11
- **Start here:** 👉 **[Testform Documentation Portal (docs/index.md)](docs/index.md)** 👈
28
+ Comprehensive guides, API specifications, and interactive references are hosted at our documentation portal:
12
29
 
13
- ### Quick Links
14
- - **[Getting Started](docs/getting-started.md)**: Installation, authentication, and your first `apply`.
15
- - **[Writing Tests (The DSL)](docs/writing-tests-dsl.md)**: Master the Gherkin syntax, tags, and custom fields (like `assignees` and `milestone`).
16
- - **[Configuration Guide](docs/configuration.md)**: Deep dive into the `testform.json` rules.
17
- - **[CLI Reference](docs/cli-reference.md)**: Cheat sheet for all commands (`plan`, `apply`, `import`, etc.).
18
- - **[Reporting & Analytics](docs/reporting-and-analytics.md)**: Generate execution matrices and coverage reports locally.
19
- - **[Architecture](docs/architecture.md)**: How the AST parser, state management, and GraphQL adapters work.
30
+ 👉 **[Official Testform Documentation Portal](https://fromeroc9.github.io/testform-docs/)**
31
+ - **Repository:** [fromeroc9/testform-docs](https://github.com/fromeroc9/testform-docs)
32
+ - **Quickstart & Guides:** Architecture, Providers, Multi-Cloud State, Target Scoping, and Modular Reporting.
20
33
 
21
34
  ---
22
35
 
23
36
  ## Prerequisites
24
37
 
25
- To use Testform, it is a requirement to have an existing GitHub Project properly configured with the necessary labels and status fields.
38
+ Testform supports two operational modes depending on your team's workflow:
39
+
40
+ ### 1. Local / Offline Mode (Zero Configuration)
41
+ If you configure `provider: local` and `backend: local`, **no external services, tokens, or credentials are required**. Testform works 100% offline out-of-the-box, storing your test management state locally in `testform.state` or committing it directly to Git.
42
+
43
+ ### 2. GitHub Provider Mode (`provider: github`)
44
+ When synchronizing your test specifications with GitHub Issues and GitHub Projects, your repository and organization must meet the following prerequisites:
45
+
46
+ 1. **GitHub Project (Projects V2):**
47
+ - An active GitHub Project (organization or user level) linked to your target repository.
48
+ - A single-select field named strictly **`Status`** containing the following exact option values:
49
+ - `Todo`
50
+ - `Done`
51
+ - `passed`
52
+ - `failed`
53
+ - `blocked`
54
+ - `skipped`
55
+ - `unexecuted`
56
+
57
+ 2. **Repository Labels:**
58
+ - The repository requires the following 5 labels to categorize issues:
59
+ - `bug`
60
+ - `testcase`
61
+ - `testplan`
62
+ - `testreport`
63
+ - `testrun`
64
+
65
+ 3. **Authentication & Token Permissions:**
66
+ - A **Personal Access Token (PAT)** with:
67
+ - **Classic PAT:** `repo` (Full control of private repositories) and `project` (Read and write projects) scopes.
68
+ - **Fine-Grained PAT:** Repository permissions (`Issues: Read and write`) and Organization permissions (`Projects: Read and write`).
69
+ - Exported as an environment variable (e.g. `export GITHUB_TOKEN="ghp_..."`) or provided via `testform login`.
70
+ - > **💡 GitHub Actions Note:** The default `GITHUB_TOKEN` provided by Actions lacks the necessary scopes to manipulate organization-level GitHub Projects (V2). Always configure a repository secret with a dedicated PAT (e.g., `secrets.TESTFORM_GITHUB_TOKEN`) so automated CI/CD pipelines can transition issues and sync project boards.
71
+
72
+ 4. **🚀 Automated Setup Workflow (Recommended):**
73
+ To automate the entire GitHub Project and label setup in seconds, we recommend using our automated **[Install Testform Labels and Project](.github/workflows/install.yml)** workflow. It will automatically:
74
+ - Create the required repository labels (`bug`, `testcase`, `testplan`, `testreport`, `testrun`).
75
+ - Clone the [Testform Template Project](https://github.com/users/fromeroc9/projects/4) into your organization or user account and link it to your target repository.
76
+ - Configure the "Status" field with the correct options and standard QA colors.
77
+ - Install the `close-issue.yml` workflow into your target repository to automate issue state transitions.
78
+
79
+ ### 3. Optional Binary Drivers (Word & Excel)
80
+ For minimal CLI footprint (~1 MB), the binary document generators (`docx` and `exceljs`) are decoupled as optional peer dependencies. If you plan to generate Word (`.docx`) or Excel (`.xlsx`) reports, install them on demand:
26
81
 
27
- We highly recommend using our automated **[Install Testform Labels and Project](.github/workflows/install.yml)** workflow to set everything up for you. This workflow will automatically:
28
- - Create the required repository labels (`bug`, `testcase`, `testplan`, `testreport`, `testrun`).
29
- - Clone the [Testform Template Project](https://github.com/users/fromeroc9/projects/4) into your organization or user account and link it to your target repository.
30
- - Configure the "Status" field with the correct options and colors (`Todo`, `Done`, `passed`, `failed`, `blocked`, `skipped`, `unexecuted`).
31
- - Install the `close-issue.yml` workflow into your target repository to automate issue state transitions.
82
+ ```bash
83
+ npm install -g docx exceljs
84
+ # or locally in your project:
85
+ npm install --save-dev docx exceljs
86
+ ```
32
87
 
33
- > **💡 Authentication Recommendation:** If you plan to use Testform within GitHub Actions, or authenticate via `testform login` (or equivalent CLI login), we strongly advise configuring a **Personal Access Token (PAT)** (with `repo` and `project` permissions). *Note: It is neither mandatory nor recommended to use a GitHub App token.*
34
- >
35
- > *Why?* The default `GITHUB_TOKEN` provided by Actions often lacks the necessary scopes to manipulate organization-level GitHub Projects (V2) or perform cross-repository operations. Using a dedicated PAT ensures that your automated pipelines have the robust, fine-grained access required to smoothly transition issues, manage test cases, and keep your project boards flawlessly in sync.
88
+ ---
36
89
 
37
90
  ## Installation
38
91
 
39
- You can install Testform directly onto your system using npm. It is distributed as a global Node.js package:
92
+ Testform is distributed as a global CLI tool via npm:
40
93
 
41
94
  ```bash
42
- npm install -g testform
95
+ npm install -g @fromeroc9/testform@beta
43
96
  ```
44
97
 
45
- > **Note:** Testform requires Node.js v16 or higher to be installed on your system.
98
+ Verify your installation:
46
99
 
47
- ## Quickstart (TL;DR)
100
+ ```bash
101
+ testform -version
102
+ ```
48
103
 
49
- 1. Create a `testform.json` configuration file at the root of your project:
50
- ```json
51
- {
52
- "github": {
53
- "owner": "MyOrg",
54
- "repository": "MyRepo",
55
- "tokenEnv": "GITHUB_TOKEN"
56
- },
57
- "scope": {
58
- "testcase": {
59
- "fields": [
60
- { "name": "assignees", "type": "keywords" },
61
- { "name": "priority", "type": "tags", "values": ["@high", "@medium", "@low"] }
62
- ]
63
- }
64
- }
65
- }
66
- ```
104
+ > **Note:** Testform requires **Node.js v18.0.0** or higher.
105
+
106
+ ---
67
107
 
68
- 2. Initialize your workspace:
108
+ ## Quickstart (TL;DR)
109
+
110
+ 1. Initialize your workspace (generates the `main.yml` manifest and backend ledger):
69
111
  ```bash
70
112
  testform init
71
113
  ```
72
114
 
73
- 3. Write a Gherkin file (e.g., `login.case.feature`):
115
+ This produces the root `main.yml` configuration:
116
+ ```yaml
117
+ testform:
118
+ required_version: ">= 1.0.0"
119
+ backend:
120
+ local:
121
+ path: "testform.state"
122
+
123
+ provider:
124
+ local: {}
125
+
126
+ variable:
127
+ app_url:
128
+ type: string
129
+ default: "https://www.saucedemo.com"
130
+ environment:
131
+ type: string
132
+ default: "dev"
133
+
134
+ local:
135
+ base_url: "${var.app_url}"
136
+ login_url: "${local.base_url}"
137
+
138
+ scopes:
139
+ testcase:
140
+ match: "*.case.feature"
141
+ testrun:
142
+ match: "*.run.feature"
143
+ testplan:
144
+ match: "*.plan.feature"
145
+ ```
146
+
147
+ 2. Write declarative BDD tests with variables and locals (e.g., `login.case.feature`):
74
148
  ```gherkin
75
149
  @testcase
76
150
  Feature: User Login
77
151
 
78
- @high
79
- Scenario: Valid Login
80
- * field assignees = @octocat
81
- Given the user is on the login page
152
+ @tc-1 @smoke @auth
153
+ Scenario: Valid Standard Login
154
+ Given the user navigates to "${local.login_url}"
155
+ When the user enters credentials "standard_user" / "secret_sauce"
156
+ Then the system redirects to "${var.app_url}/inventory.html"
82
157
  ```
83
158
 
84
- 4. Preview the changes and apply them to GitHub:
159
+ 3. Validate, preview, apply, and report:
85
160
  ```bash
86
- testform plan
87
- testform apply
161
+ # Validate syntax and configuration
162
+ testform validate
163
+
164
+ # Plan execution with variable overrides (optional)
165
+ testform plan -var-file=staging.yml
166
+
167
+ # Apply to local state or remote provider
168
+ testform apply -auto-approve
169
+
170
+ # Inspect state resources using dot notation
171
+ testform state list
172
+ testform state show local_testcase.login.case.feature.@tc-1
173
+
174
+ # Generate multi-format execution reports (Markdown, Word, Excel, JSON, CSV)
175
+ testform report testrun-summary -format=md
176
+ testform report testcase-summary -format=docx -out=report.docx
177
+
178
+ # Scope reports by target (individual test run or entire test plan)
179
+ testform report testrun-summary -target=@tr-1
180
+ testform report testplan-summary -target=@tp-1
88
181
  ```
89
182
 
90
- For full details, please visit our **[Documentation Portal](docs/index.md)**.
183
+ ---
184
+
185
+ ## 🚀 Key Features
186
+
187
+ - **Test-as-Code Engine:** Declarative management for Testcases, Testruns, and Testplans using Gherkin.
188
+ - **Modular Reporting & Multi-Format Analytics (`testform report`):** Generates 9 multidimensional reports natively exported to Markdown, JSON, CSV, Word (`.docx`), and Excel (`.xlsx`) with `${...}` dynamic template markers, unified `-filter` queries, and zero-pollution autoloading from `.testform/reports/`.
189
+ - **Target Scoping (`-target`):** Granular scoping to single test runs or test plans with automated discovery of all linked runs and execution cases.
190
+ - **Terraform Diagnostic Standards:** All warnings and errors rendered in structured, colored HashiCorp Terraform diagnostic blocks (`╷ ... │ Error: ... ╵`).
191
+ - **5-Tier Variables Precedence:** Hierarchy spanning base `main.yml`, `variable.yml`/`local.yml`, domain modules, `-var-file`, and `-var` flags with multi-pass recursive interpolation.
192
+ - **100% Offline Capability:** Full local backend (`backend: local`) and mock provider (`provider: local`) for deterministic testing without external dependencies or tokens.
193
+ - **Terraform-grade State Management:** State locking, drift detection (`diff`), manual taint/untaint lifecycle, HCL resource display (`state show`), and dependency DAG rendering (`graph`).
194
+ - **Global Flags:** `-chdir=<path>`, `-no-color`, and `-compact-warnings` supported universally across commands.
195
+
196
+ ---
197
+
198
+ For full documentation and API specifications, visit our **[Official Documentation Portal](https://fromeroc9.github.io/testform-docs/)**.
@@ -0,0 +1,20 @@
1
+ <svg viewBox="0 0 32 32" fill="none" xmlns="http://www.w3.org/2000/svg">
2
+ <defs>
3
+ <linearGradient id="tf-stem-icon" x1="12.5" y1="15" x2="19.5" y2="28" gradientUnits="userSpaceOnUse">
4
+ <stop offset="0%" stop-color="#38bdf8" />
5
+ <stop offset="100%" stop-color="#0284c7" />
6
+ </linearGradient>
7
+ <linearGradient id="tf-top-icon" x1="12.5" y1="4" x2="19.5" y2="17" gradientUnits="userSpaceOnUse">
8
+ <stop offset="0%" stop-color="#0284c7" />
9
+ <stop offset="100%" stop-color="#4f46e5" />
10
+ </linearGradient>
11
+ </defs>
12
+ <!-- Top-Left Wing (Indigo/Violet) -->
13
+ <path d="M 3.5 13 L 10.5 9 L 10.5 18 L 3.5 22 Z" fill="#6366f1" />
14
+ <!-- Top-Center Tile (Gradient Deep Blue to Indigo) -->
15
+ <path d="M 12.5 8 L 19.5 4 L 19.5 13 L 12.5 17 Z" fill="url(#tf-top-icon)" />
16
+ <!-- Top-Right Wing (Sky Blue) -->
17
+ <path d="M 21.5 13 L 28.5 9 L 28.5 18 L 21.5 22 Z" fill="#38bdf8" />
18
+ <!-- Stem Lower Center Tile (Gradient Sky to Blue) -->
19
+ <path d="M 12.5 19 L 19.5 15 L 19.5 24 L 12.5 28 Z" fill="url(#tf-stem-icon)" />
20
+ </svg>