@analizza-ai/testspec 0.1.1 → 0.1.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.
Files changed (2) hide show
  1. package/README.md +199 -51
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -5,23 +5,28 @@
5
5
  [![license](https://img.shields.io/npm/l/@analizza-ai/testspec)](./LICENSE)
6
6
  [![node](https://img.shields.io/node/v/@analizza-ai/testspec)](./package.json)
7
7
 
8
- **Spec Driven Test — the test layer for SDD**
8
+ **Spec Driven Testing — the test layer for SDD**
9
9
 
10
- testspec (SDT) inverts traditional test generation. Instead of writing code first and covering it with tests, SDT drives the entire test lifecycle from your spec artifacts. Specs are the single source of truth.
10
+ > `Spec Driven Development` — Unit tests · Integration tests · Testcontainers
11
+ > `Spec Driven Testing` — End-to-end · Load · Chaos Engineering · UI · Exploratory
12
+
13
+ testspec installs 4 Claude Code slash commands that cover the full SDT lifecycle — from developer tests to QA automation. Specs are the single source of truth. Tests are derived, never invented.
11
14
 
12
15
  ---
13
16
 
14
17
  ## Test pyramid
15
18
 
19
+ <img width="521" height="478" alt="image" src="https://github.com/user-attachments/assets/a07d3ab0-8cd9-4746-b59a-bb8ea2773f63" />
20
+
16
21
  ```
17
22
  ┌─────────────────────────────────────────────────┐
18
23
  │ CHAOS ENGINEERING │ ← /testspec-run-qa
19
24
  │ (resilience · DR · fault injection) │
20
25
  ├─────────────────────────────────────────────────┤
21
- │ QA LAYER │ ← /testspec-apply-qa
26
+ │ QA LAYER │ ← /testspec-specify-qa → /testspec-apply-qa
22
27
  │ end-to-end tests · load tests (k6/Gatling) │
23
28
  ├─────────────────────────────────────────────────┤
24
- │ DEVELOPER LAYER │ ← testspec generate
29
+ │ DEVELOPER LAYER │ ← /testspec-generate
25
30
  │ unit tests · integration tests (Testcontainers│
26
31
  │ PostgreSQL · Kafka · etc.) │
27
32
  └─────────────────────────────────────────────────┘
@@ -31,15 +36,79 @@ testspec (SDT) inverts traditional test generation. Instead of writing code firs
31
36
 
32
37
  ---
33
38
 
34
- ## What is SDT
39
+ ## Full development + test flow
40
+
41
+ ```mermaid
42
+ flowchart TD
43
+ IDEA["💡 Idea / Demand"]
44
+
45
+ IDEA --> PROPOSE
46
+
47
+ subgraph OPENSPEC["OpenSpec — Spec-Driven Development (app repo)"]
48
+ PROPOSE["/opsx:propose\nDescribes what will be built"]
49
+
50
+ PROPOSE --> PROPOSAL["proposal.md\nIntent · Goals · Non-goals"]
51
+ PROPOSE --> SPECS["specs/{feature}/spec.md\nWhat the system must do"]
52
+ PROPOSE --> DESIGN["design.md\nHow — Architecture · Contracts · Decisions"]
53
+
54
+ PROPOSAL --> TESTS_CMD
55
+ SPECS --> TESTS_CMD
56
+ DESIGN --> TESTS_CMD
57
+
58
+ TESTS_CMD["/testspec-generate\nConsolidates specs and generates test cases"]
59
+ TESTS_CMD --> TESTS_MD["tests.md\nCT-01..N · Happy path · Business rules · DB"]
60
+
61
+ TESTS_MD --> TASKS["tasks.md\nTasks in chunks of up to 2h"]
62
+ end
63
+
64
+ TASKS --> APPLY
65
+
66
+ subgraph IMPL["Implementation (app repo)"]
67
+ APPLY["/opsx:apply\nExecutes tasks from the change"]
68
+ APPLY --> CODE["Code · Migrations · Integration tests"]
69
+ CODE --> VERIFY["Testcontainers\nPostgreSQL + Kafka"]
70
+ end
71
+
72
+ VERIFY --> ARCHIVE["/opsx:archive\nChange archived as complete"]
73
+
74
+ ARCHIVE --> SPECIFY_QA
35
75
 
36
- testspec reads the spec artifacts produced by your SDD framework (OpenSpec, SpecKit, etc.) and generates:
76
+ subgraph QA["Autonomous QA (separate QA repo)"]
77
+ SPECIFY_QA["/testspec-specify-qa\nQuestionnaire: tool · types · technical contract"]
78
+ SPECIFY_QA --> SPEC_MD["spec.qa.md\nCT → k6/Gatling script mapping"]
79
+ SPECIFY_QA --> TASKS_MD["tasks.qa.md\nChecklist of scripts to implement"]
37
80
 
38
- 1. **`tests.md`** — a technology-agnostic test document with numbered CT-01..N test cases
39
- 2. **Unit test stubs** — Jest / Vitest / Pytest / JUnit skeletons named after CTs
40
- 3. **Integration test stubs** — Testcontainers-based, pre-configured for your stack
81
+ TASKS_MD --> APPLY_QA
82
+ SPEC_MD --> APPLY_QA
41
83
 
42
- The QA layer then consumes `tests.md` to generate k6/Gatling scripts without ambiguity.
84
+ APPLY_QA["/testspec-apply-qa\nGenerates scripts + run plans .md"]
85
+ APPLY_QA --> E2E["e2e/\nk6-e2e-{action}-{scenario}.js\nk6-e2e-{action}-{scenario}.md"]
86
+ APPLY_QA --> LOAD["load/\nk6-load-{action}-{scenario}-{rps}-rps-{dur}.js\nk6-load-{action}-{scenario}-{rps}-rps-{dur}.md"]
87
+ APPLY_QA --> CHAOS["chaos-engineering/\nk6-dr-{action}-{scenario}-{type}.js\nk6-dr-{action}-{scenario}-{type}.md"]
88
+
89
+ E2E --> RUN_QA
90
+ LOAD --> RUN_QA
91
+ CHAOS --> RUN_QA
92
+
93
+ RUN_QA["/testspec-run-qa\nAI execution agent"]
94
+ RUN_QA --> EXEC["Runs script\nCaptures stdout · p95/p99/RPS metrics"]
95
+ EXEC --> LOGS["Collects logs\nkubectl + Splunk via MCP"]
96
+ LOGS --> DB["Analyzes DB\nSELECT via MCP DB"]
97
+ DB --> REPORT["Generates Markdown report\nSummary · Metrics · Criteria · Logs · DB"]
98
+ REPORT --> CONFLUENCE["Publishes to Confluence via MCP\n(fallback: ./reports/ local)"]
99
+ end
100
+
101
+ style OPENSPEC fill:#1e1e2e,stroke:#cba6f7,color:#cdd6f4
102
+ style IMPL fill:#1e1e2e,stroke:#89b4fa,color:#cdd6f4
103
+ style QA fill:#1e1e2e,stroke:#a6e3a1,color:#cdd6f4
104
+ style IDEA fill:#313244,stroke:#f38ba8,color:#cdd6f4
105
+ style ARCHIVE fill:#313244,stroke:#a6e3a1,color:#cdd6f4
106
+ style TESTS_CMD fill:#45475a,stroke:#f9e2af,color:#cdd6f4
107
+ style SPECIFY_QA fill:#45475a,stroke:#f9e2af,color:#cdd6f4
108
+ style APPLY_QA fill:#45475a,stroke:#89b4fa,color:#cdd6f4
109
+ style RUN_QA fill:#45475a,stroke:#a6e3a1,color:#cdd6f4
110
+ style CONFLUENCE fill:#313244,stroke:#a6e3a1,color:#cdd6f4
111
+ ```
43
112
 
44
113
  ---
45
114
 
@@ -58,12 +127,25 @@ testspec report
58
127
 
59
128
  ---
60
129
 
130
+ ## Skills
131
+
132
+ `testspec init` installs these 4 slash commands into your project's `.claude/commands/`:
133
+
134
+ | # | Skill | Layer | What it does |
135
+ |---|-------|-------|--------------|
136
+ | 1 | `/testspec-generate` | Developer | Consolidates all `spec.md` files for the feature and generates `tests.md` — a technology-agnostic document with numbered test cases (CT-01..N), acceptance criteria, DB validations, and out-of-scope boundaries |
137
+ | 2 | `/testspec-specify-qa` | QA | Creates `testspec/` and `instructions.md` automatically if missing. Reads `tests.md` via GitHub MCP, runs a questionnaire (tool, test types, technical contract JSON) and generates `spec.qa.md` + `tasks.qa.md` + folder structure |
138
+ | 3 | `/testspec-apply-qa` | QA | Implements k6/Gatling scripts from `tasks.qa.md` using `spec.qa.md` as the contract. Auto-generates a `.md` run plan alongside each script. Marks tasks `[x]` immediately after each pair is created |
139
+ | 4 | `/testspec-run-qa` | QA / Chaos | AI agent: reads the run plan `.md`, executes the script, collects logs (kubectl + Splunk via MCP), queries the DB via MCP, generates a Markdown report, and publishes to Confluence. Never cancels the suite on failure — reports everything and continues |
140
+
141
+ ---
142
+
61
143
  ## How it works
62
144
 
63
145
  ```
64
146
  Spec artifacts (proposal.md · design.md · specs/**/*.md · tasks.md)
65
147
  ↓
66
- testspec generate
148
+ testspec generate (/testspec-generate)
67
149
  ↓
68
150
  SpecContext (scenarios, rules, contracts, dbAssertions)
69
151
  ↓
@@ -74,8 +156,98 @@ tests.md (CT-01..N)
74
156
  Unit stubs + Integration stubs (Testcontainers)
75
157
  ↓
76
158
  QA repo reads tests.md via GitHub MCP
77
- ↓
78
- k6 / Gatling scripts · chaos scripts
159
+ ↓ /testspec-specify-qa
160
+ spec.qa.md + tasks.qa.md
161
+ ↓ /testspec-apply-qa
162
+ k6 / Gatling scripts · run plans .md
163
+ ↓ /testspec-run-qa
164
+ Execution · Metrics · Logs · Report → Confluence
165
+ ```
166
+
167
+ ---
168
+
169
+ ## OpenSpec structure (app repo)
170
+
171
+ ```
172
+ openspec/
173
+ ├── config.yaml # stack, conventions and global rules
174
+ ├── specs/ # reusable specs (global)
175
+ └── changes/
176
+ ├── archive/ # completed changes (/opsx:archive)
177
+ └── {change-name}/
178
+ ├── proposal.md # context, goals, non-goals
179
+ ├── design.md # architecture, contracts, decisions
180
+ ├── specs/
181
+ │ └── {feature}/
182
+ │ └── spec.md # behaviour specification
183
+ ├── tests.md # test cases generated by /testspec-generate
184
+ └── tasks.md # tasks ready for /opsx:apply
185
+ ```
186
+
187
+ ## QA repo structure
188
+
189
+ ```
190
+ testspec/
191
+ ├── instructions.md # app_repo (GitHub owner/repo), MCPs, QA project standards
192
+ ├── current-feature.md # feature in focus for the current session (written by skills)
193
+ └── {feature-name}/
194
+ ├── spec.qa.md # technical contract: request · response · rules · CT → script mapping
195
+ └── tasks.qa.md # checklist [ ] / [x] of scripts to implement
196
+
197
+ src/test/features/
198
+ └── {feature-name}/
199
+ ├── e2e/
200
+ │ ├── {tool}-e2e-{action}-{scenario}.js # functional script — 1 per CT
201
+ │ └── {tool}-e2e-{action}-{scenario}.md # run plan — read by /testspec-run-qa
202
+ ├── load/
203
+ │ ├── {tool}-load-{action}-{scenario}-{rps}-rps-{dur}.js
204
+ │ └── {tool}-load-{action}-{scenario}-{rps}-rps-{dur}.md
205
+ └── chaos-engineering/
206
+ ├── {tool}-dr-{action}-{scenario}-{type}.js
207
+ └── {tool}-dr-{action}-{scenario}-{type}.md
208
+
209
+ reports/
210
+ └── {feature-name}/
211
+ └── {script}-{YYYY-MM-DD-HHmm}.md # report generated by /testspec-run-qa
212
+ # (fallback when Confluence unavailable)
213
+ ```
214
+
215
+ ---
216
+
217
+ ## tests.md format
218
+
219
+ ```yaml
220
+ ---
221
+ feature: Item Creation
222
+ change: item-creation
223
+ generated: 2026-05-25T10:00:00.000Z
224
+ sdd: openspec
225
+ sdt: 0.1.0
226
+ stack: { lang: node, db: postgresql }
227
+ qa-repo: analizza-ai/qa
228
+ ---
229
+
230
+ # Tests — Item Creation
231
+
232
+ ## Scope
233
+ ## Out of scope
234
+
235
+ ## Test cases
236
+
237
+ ### CT-01 — Create item with valid payload
238
+
239
+ | Field | Value |
240
+ |---------------------|------------------------------------|
241
+ | Type | integration |
242
+ | Layer | developer |
243
+ | Precondition | User is authenticated |
244
+ | Input | POST /api/items { name: "x" } |
245
+ | Expected output | 201 Created { id: 1 } |
246
+ | DB validation | SELECT id FROM items WHERE id = 1 |
247
+ | Acceptance criteria | · item persisted · id returned |
248
+
249
+ ## Load profile hints
250
+ ## Chaos scenarios
79
251
  ```
80
252
 
81
253
  ---
@@ -116,44 +288,6 @@ k6 / Gatling scripts · chaos scripts
116
288
 
117
289
  ---
118
290
 
119
- ## tests.md format
120
-
121
- ```yaml
122
- ---
123
- feature: Item Creation
124
- change: item-creation
125
- generated: 2026-05-25T10:00:00.000Z
126
- sdd: openspec
127
- sdt: 0.1.0
128
- stack: { lang: node, db: postgresql }
129
- qa-repo: analizza-ai/qa
130
- ---
131
-
132
- # Tests — Item Creation
133
-
134
- ## Scope
135
- ## Out of scope
136
-
137
- ## Test cases
138
-
139
- ### CT-01 — Create item with valid payload
140
-
141
- | Field | Value |
142
- |---------------------|------------------------------|
143
- | Type | integration |
144
- | Layer | developer |
145
- | Precondition | User is authenticated |
146
- | Input | POST /api/items { name: "x" }|
147
- | Expected output | 201 Created { id: 1 } |
148
- | DB validation | SELECT id FROM items WHERE id = 1 |
149
- | Acceptance criteria | · item persisted · id returned |
150
-
151
- ## Load profile hints
152
- ## Chaos scenarios
153
- ```
154
-
155
- ---
156
-
157
291
  ## Configuration
158
292
 
159
293
  `testspec.config.json` in your project root:
@@ -172,6 +306,20 @@ qa-repo: analizza-ai/qa
172
306
 
173
307
  ---
174
308
 
309
+ ## CI/CD
310
+
311
+ This package is published to npmjs automatically via GitHub Actions on every `v*` tag.
312
+
313
+ | Workflow | Trigger | What it does |
314
+ |----------|---------|--------------|
315
+ | `ci.yml` | Push / PR to `main` | Lint + test on Node 20 and 22 |
316
+ | `release.yml` | Manual (`workflow_dispatch`) | Bumps version, commits, pushes tag |
317
+ | `publish.yml` | Tag `v*` push or manual | Publishes to npmjs with provenance |
318
+
319
+ To release a new version: **GitHub → Actions → Release → Run workflow → pick `patch` / `minor` / `major`**.
320
+
321
+ ---
322
+
175
323
  ## Adapter extension guide
176
324
 
177
325
  See [docs/adapters-sdd.md](docs/adapters-sdd.md) to add a custom SDD framework adapter.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@analizza-ai/testspec",
3
- "version": "0.1.1",
3
+ "version": "0.1.2",
4
4
  "description": "Spec Driven Test — the test layer for SDD",
5
5
  "type": "module",
6
6
  "bin": {