@fromeroc9/testform 1.1.0-beta.0 → 1.1.0-beta.2

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,56 +1,127 @@
1
1
  <p align="center">
2
- <img src="docs/public/testform-logo.svg" alt="Testform Logo" width="80" height="80" />
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>Declarative Test-as-Code Framework for Git & Testing Platforms</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** 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.
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
- We have completely overhauled our documentation to be as intuitive and comprehensive as possible.
28
+ Comprehensive guides, API specifications, and interactive references are hosted at our documentation portal:
20
29
 
21
- **Start here:** 👉 **[Testform Documentation Portal (docs/index.md)](docs/index.md)** 👈
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
- 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:
93
+
94
+ ```bash
95
+ npm install -g @fromeroc9/testform@beta
96
+ ```
97
+
98
+ Verify your installation:
40
99
 
41
100
  ```bash
42
- npm install -g testform
101
+ testform -version
43
102
  ```
44
103
 
45
- > **Note:** Testform requires Node.js v16 or higher to be installed on your system.
104
+ > **Note:** Testform requires **Node.js v18.0.0** or higher.
105
+
106
+ ---
46
107
 
47
108
  ## Quickstart (TL;DR)
48
109
 
49
- 1. Create a `testform.yml` configuration file at the root of your project:
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
- version: "1.0"
52
- provider: local
53
- backend: local
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. Initialize your workspace (backend ledger and providers):
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
- 4. Validate, preview, and apply your test infrastructure:
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
- For full details, please visit our **[Documentation Portal (docs/)](docs/)**.
196
+ ---
116
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>