@fromeroc9/testform 1.1.0-beta.0 → 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 +111 -29
- package/assets/logo.svg +20 -0
- package/dist/index.js +2 -2
- package/package.json +96 -84
- package/templates/report.docx +0 -0
- package/templates/report.xlsx +0 -0
package/README.md
CHANGED
|
@@ -1,56 +1,127 @@
|
|
|
1
1
|
<p align="center">
|
|
2
|
-
<img src="
|
|
2
|
+
<img src="assets/logo.svg" alt="Testform Logo" width="80" height="80" />
|
|
3
3
|
</p>
|
|
4
4
|
|
|
5
5
|
<h1 align="center">Testform</h1>
|
|
6
6
|
|
|
7
7
|
<p align="center">
|
|
8
|
-
<strong>
|
|
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>
|
|
9
18
|
</p>
|
|
10
19
|
|
|
11
20
|
---
|
|
12
21
|
|
|
13
|
-
**Testform**
|
|
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.
|
|
14
23
|
|
|
15
24
|
---
|
|
16
25
|
|
|
17
26
|
## 📚 Documentation
|
|
18
27
|
|
|
19
|
-
|
|
28
|
+
Comprehensive guides, API specifications, and interactive references are hosted at our documentation portal:
|
|
20
29
|
|
|
21
|
-
|
|
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.
|
|
33
|
+
|
|
34
|
+
---
|
|
22
35
|
|
|
23
36
|
## Prerequisites
|
|
24
37
|
|
|
25
|
-
|
|
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
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
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
|
-
|
|
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
|
-
|
|
92
|
+
Testform is distributed as a global CLI tool via npm:
|
|
93
|
+
|
|
94
|
+
```bash
|
|
95
|
+
npm install -g @fromeroc9/testform@beta
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
Verify your installation:
|
|
40
99
|
|
|
41
100
|
```bash
|
|
42
|
-
|
|
101
|
+
testform -version
|
|
43
102
|
```
|
|
44
103
|
|
|
45
|
-
> **Note:** Testform requires Node.js
|
|
104
|
+
> **Note:** Testform requires **Node.js v18.0.0** or higher.
|
|
105
|
+
|
|
106
|
+
---
|
|
46
107
|
|
|
47
108
|
## Quickstart (TL;DR)
|
|
48
109
|
|
|
49
|
-
1.
|
|
110
|
+
1. Initialize your workspace (generates the `main.yml` manifest and backend ledger):
|
|
111
|
+
```bash
|
|
112
|
+
testform init
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
This produces the root `main.yml` configuration:
|
|
50
116
|
```yaml
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
117
|
+
testform:
|
|
118
|
+
required_version: ">= 1.0.0"
|
|
119
|
+
backend:
|
|
120
|
+
local:
|
|
121
|
+
path: "testform.state"
|
|
122
|
+
|
|
123
|
+
provider:
|
|
124
|
+
local: {}
|
|
54
125
|
|
|
55
126
|
variable:
|
|
56
127
|
app_url:
|
|
@@ -67,14 +138,13 @@ npm install -g testform
|
|
|
67
138
|
scopes:
|
|
68
139
|
testcase:
|
|
69
140
|
match: "*.case.feature"
|
|
141
|
+
testrun:
|
|
142
|
+
match: "*.run.feature"
|
|
143
|
+
testplan:
|
|
144
|
+
match: "*.plan.feature"
|
|
70
145
|
```
|
|
71
146
|
|
|
72
|
-
2.
|
|
73
|
-
```bash
|
|
74
|
-
testform init
|
|
75
|
-
```
|
|
76
|
-
|
|
77
|
-
3. Write your Gherkin tests with variables and locals (e.g., `login.case.feature`):
|
|
147
|
+
2. Write declarative BDD tests with variables and locals (e.g., `login.case.feature`):
|
|
78
148
|
```gherkin
|
|
79
149
|
@testcase
|
|
80
150
|
Feature: User Login
|
|
@@ -86,7 +156,7 @@ npm install -g testform
|
|
|
86
156
|
Then the system redirects to "${var.app_url}/inventory.html"
|
|
87
157
|
```
|
|
88
158
|
|
|
89
|
-
|
|
159
|
+
3. Validate, preview, apply, and report:
|
|
90
160
|
```bash
|
|
91
161
|
# Validate syntax and configuration
|
|
92
162
|
testform validate
|
|
@@ -100,6 +170,14 @@ npm install -g testform
|
|
|
100
170
|
# Inspect state resources using dot notation
|
|
101
171
|
testform state list
|
|
102
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
|
|
103
181
|
```
|
|
104
182
|
|
|
105
183
|
---
|
|
@@ -107,10 +185,14 @@ npm install -g testform
|
|
|
107
185
|
## 🚀 Key Features
|
|
108
186
|
|
|
109
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: ... ╵`).
|
|
110
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.
|
|
111
192
|
- **100% Offline Capability:** Full local backend (`backend: local`) and mock provider (`provider: local`) for deterministic testing without external dependencies or tokens.
|
|
112
193
|
- **Terraform-grade State Management:** State locking, drift detection (`diff`), manual taint/untaint lifecycle, HCL resource display (`state show`), and dependency DAG rendering (`graph`).
|
|
113
194
|
- **Global Flags:** `-chdir=<path>`, `-no-color`, and `-compact-warnings` supported universally across commands.
|
|
114
195
|
|
|
115
|
-
|
|
196
|
+
---
|
|
116
197
|
|
|
198
|
+
For full documentation and API specifications, visit our **[Official Documentation Portal](https://fromeroc9.github.io/testform-docs/)**.
|
package/assets/logo.svg
ADDED
|
@@ -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>
|