@t0.labs/daxta 1.1.2 → 1.1.4
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 +123 -55
- package/assets/example.html +623 -86
- package/assets/viewer.html +1027 -191
- package/dist/build/build-spec.js +173 -21
- package/dist/catalog/index.d.ts +1 -0
- package/dist/catalog/index.js +23 -10
- package/dist/catalog/it-case.js +2 -0
- package/dist/catalog/test-title.js +7 -5
- package/dist/cli/install.js +18 -16
- package/dist/cli/titles.js +41 -9
- package/dist/cli/tree.js +14 -4
- package/dist/cli/uninstall.js +2 -1
- package/dist/config.d.ts +24 -1
- package/dist/config.js +69 -2
- package/dist/fields/dto-fields.js +28 -2
- package/dist/index.d.ts +2 -2
- package/dist/index.js +5 -1
- package/dist/jest/global-setup.js +1 -0
- package/dist/jest/global-teardown.js +4 -0
- package/dist/jest/reporter.d.ts +2 -0
- package/dist/jest/reporter.js +23 -2
- package/dist/recorder/index.d.ts +6 -0
- package/dist/recorder/index.js +36 -3
- package/dist/serve/index.d.ts +1 -1
- package/dist/serve/index.js +2 -1
- package/dist/serve/middleware.d.ts +3 -4
- package/dist/serve/middleware.js +14 -13
- package/dist/serve/paths.d.ts +3 -0
- package/dist/serve/paths.js +12 -0
- package/dist/serve/viewer-store.d.ts +5 -2
- package/dist/serve/viewer-store.js +9 -4
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,21 +1,17 @@
|
|
|
1
|
-
<
|
|
2
|
-
<
|
|
3
|
-
|
|
1
|
+
<picture>
|
|
2
|
+
<source media="(prefers-color-scheme: dark)" srcset="assets/logo-light.png">
|
|
3
|
+
<source media="(prefers-color-scheme: light)" srcset="assets/logo-dark.png">
|
|
4
|
+
<img alt="DAxTA" src="assets/logo-dark.png" width="120" height="120">
|
|
5
|
+
</picture>
|
|
4
6
|
|
|
5
|
-
|
|
7
|
+
# DAxTA
|
|
6
8
|
|
|
7
|
-
|
|
9
|
+
**API Test → API Documentation**
|
|
8
10
|
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
Don't document the same thing twice.
|
|
12
|
-
</p>
|
|
11
|
+
You already wrote the tests.
|
|
12
|
+
Don't document the same thing twice.
|
|
13
13
|
|
|
14
|
-
|
|
15
|
-
<a href="https://www.npmjs.com/package/@t0.labs/daxta"><img alt="npm" src="https://img.shields.io/npm/v/@t0.labs/daxta?color=111111&label=npm&logo=npm" /></a>
|
|
16
|
-
<a href="https://nodejs.org"><img alt="node" src="https://img.shields.io/node/v/@t0.labs/daxta?color=111111&label=node" /></a>
|
|
17
|
-
<a href="LICENSE"><img alt="license" src="https://img.shields.io/npm/l/@t0.labs/daxta?color=111111" /></a>
|
|
18
|
-
</p>
|
|
14
|
+

|
|
19
15
|
|
|
20
16
|
---
|
|
21
17
|
|
|
@@ -30,13 +26,15 @@ DAxTA captures that real traffic while your tests run and turns it into interact
|
|
|
30
26
|
```ts
|
|
31
27
|
import { apiDocs } from '@t0.labs/daxta';
|
|
32
28
|
|
|
33
|
-
apiDocs(app); // NestJS —
|
|
29
|
+
apiDocs(app); // NestJS — mounts /docs on dev/test/staging NODE_ENV only
|
|
34
30
|
```
|
|
35
31
|
|
|
36
32
|
Generation happens when Jest finishes (reporter) or when you run `daxta generate`. You do not call `generateApiDocs()` in `main.ts`.
|
|
37
33
|
|
|
38
34
|
---
|
|
39
35
|
|
|
36
|
+
|
|
37
|
+
|
|
40
38
|
## Why DAxTA?
|
|
41
39
|
|
|
42
40
|
When you build an API, you already describe its behavior in your tests.
|
|
@@ -74,19 +72,23 @@ OpenAPI → Postman / other tools
|
|
|
74
72
|
|
|
75
73
|
---
|
|
76
74
|
|
|
75
|
+
|
|
76
|
+
|
|
77
77
|
## What you get
|
|
78
78
|
|
|
79
|
-
|
|
80
|
-
|
|
|
81
|
-
|
|
|
82
|
-
|
|
|
83
|
-
|
|
|
84
|
-
|
|
|
85
|
-
|
|
|
86
|
-
|
|
|
87
|
-
|
|
|
88
|
-
|
|
|
89
|
-
|
|
|
79
|
+
|
|
80
|
+
| From your tests | In DAxTA |
|
|
81
|
+
| ----------------------------- | ------------------------------- |
|
|
82
|
+
| Real request / response pairs | Interactive `/api-docs` UI |
|
|
83
|
+
| Positive scenarios | Success examples |
|
|
84
|
+
| Negative scenarios | Error examples |
|
|
85
|
+
| Validation failures | Invalid cases |
|
|
86
|
+
| Authentication scenarios | Recorded headers |
|
|
87
|
+
| Omitted / optional fields | DTO field metadata |
|
|
88
|
+
| Status codes | Executable API calls |
|
|
89
|
+
| Multiple test cases | Multiple examples per operation |
|
|
90
|
+
| Recorded API set | OpenAPI + Postman export |
|
|
91
|
+
|
|
90
92
|
|
|
91
93
|
Different tests for the same endpoint automatically become different API examples.
|
|
92
94
|
|
|
@@ -104,6 +106,8 @@ These examples come from **actual test executions**, not manually maintained doc
|
|
|
104
106
|
|
|
105
107
|
---
|
|
106
108
|
|
|
109
|
+
|
|
110
|
+
|
|
107
111
|
## How it works
|
|
108
112
|
|
|
109
113
|
```text
|
|
@@ -130,19 +134,16 @@ These examples come from **actual test executions**, not manually maintained doc
|
|
|
130
134
|
```
|
|
131
135
|
|
|
132
136
|
1. **Install** attaches DAxTA to Jest using `setupFilesAfterEnv` and a reporter.
|
|
133
|
-
|
|
134
|
-
Your existing `test:integration` command remains the entrypoint. DAxTA does not wrap your test process.
|
|
135
|
-
|
|
137
|
+
Your existing `test:integration` command remains the entrypoint. DAxTA does not wrap your test process.
|
|
136
138
|
2. **Run your tests normally.**
|
|
137
|
-
|
|
138
|
-
DAxTA records the real HTTP traffic generated by your tests.
|
|
139
|
-
|
|
139
|
+
DAxTA records the real HTTP traffic generated by your tests.
|
|
140
140
|
3. **When Jest finishes**, DAxTA performs a single documentation build.
|
|
141
|
-
|
|
142
|
-
4. `apiDocs(app)` mounts the generated documentation on your NestJS application when `DAXTA_DOCS=on`.
|
|
141
|
+
4. `apiDocs(app)` mounts the generated documentation on your NestJS application in every environment except production.
|
|
143
142
|
|
|
144
143
|
---
|
|
145
144
|
|
|
145
|
+
|
|
146
|
+
|
|
146
147
|
## What DAxTA covers
|
|
147
148
|
|
|
148
149
|
DAxTA records **real HTTP traffic** from NestJS API integration tests.
|
|
@@ -163,18 +164,22 @@ If Jest is wired (`setupFilesAfterEnv` + reporter), those hits become `/api-docs
|
|
|
163
164
|
|
|
164
165
|
**Not covered** — anything that never passes through that HTTP client:
|
|
165
166
|
|
|
166
|
-
|
|
167
|
-
|
|
|
168
|
-
|
|
|
169
|
-
|
|
|
170
|
-
|
|
|
171
|
-
|
|
|
172
|
-
|
|
|
167
|
+
|
|
168
|
+
| Test style | Recorded? |
|
|
169
|
+
| -------------------------------------------------- | --------- |
|
|
170
|
+
| Nest e2e with `request(app.getHttpServer())` | Yes |
|
|
171
|
+
| Service / unit tests (`TestingModule`, no HTTP) | No |
|
|
172
|
+
| `axios`, `fetch`, `got` | No |
|
|
173
|
+
| Playwright / Cypress | No |
|
|
174
|
+
| GraphQL or WebSocket (unless over superagent HTTP) | No |
|
|
175
|
+
|
|
173
176
|
|
|
174
177
|
If the test does not hit the API over HTTP the way your clients do, DAxTA has nothing to document. That is intentional: the source of truth is **observed API behavior**, not mocked internals.
|
|
175
178
|
|
|
176
179
|
---
|
|
177
180
|
|
|
181
|
+
|
|
182
|
+
|
|
178
183
|
## Install
|
|
179
184
|
|
|
180
185
|
```bash
|
|
@@ -197,10 +202,10 @@ pnpm run test:integration
|
|
|
197
202
|
|
|
198
203
|
When Jest finishes, your documentation is ready.
|
|
199
204
|
|
|
200
|
-
Start your application
|
|
205
|
+
Start your application as usual:
|
|
201
206
|
|
|
202
207
|
```bash
|
|
203
|
-
|
|
208
|
+
pnpm start:dev
|
|
204
209
|
```
|
|
205
210
|
|
|
206
211
|
Open:
|
|
@@ -217,6 +222,40 @@ Flags: `--yes` · `--dry-run` · `--skip-main` · `--skip-dep` · `--main <path>
|
|
|
217
222
|
|
|
218
223
|
---
|
|
219
224
|
|
|
225
|
+
|
|
226
|
+
|
|
227
|
+
## Uninstall
|
|
228
|
+
|
|
229
|
+
```bash
|
|
230
|
+
pnpm dlx @t0.labs/daxta uninstall
|
|
231
|
+
```
|
|
232
|
+
|
|
233
|
+
or, if DAxTA is already a dependency:
|
|
234
|
+
|
|
235
|
+
```bash
|
|
236
|
+
pnpm daxta uninstall
|
|
237
|
+
```
|
|
238
|
+
|
|
239
|
+
It unwinds everything the installer put in place: the `apiDocs(app)` call in your NestJS entrypoint, the Jest
|
|
240
|
+
reporter and setup hooks, the wrapped test script and any `daxta:*` scripts in `package.json`, `daxta.config.ts`,
|
|
241
|
+
the generated `daxta/` output directory, the `.gitignore` entries, and the legacy `DAXTA_DOCS` line if an older
|
|
242
|
+
install left one behind. `@t0.labs/daxta` itself is removed with your package manager unless you pass
|
|
243
|
+
`--keep-dep`.
|
|
244
|
+
|
|
245
|
+
Your tests are untouched — they were never DAxTA-specific to begin with.
|
|
246
|
+
|
|
247
|
+
Preview first if you want to see the plan without writing anything:
|
|
248
|
+
|
|
249
|
+
```bash
|
|
250
|
+
pnpm dlx @t0.labs/daxta uninstall --dry-run
|
|
251
|
+
```
|
|
252
|
+
|
|
253
|
+
Flags: `--yes` · `--dry-run` · `--keep-dep` · `--fast`
|
|
254
|
+
|
|
255
|
+
---
|
|
256
|
+
|
|
257
|
+
|
|
258
|
+
|
|
220
259
|
## Docs UI
|
|
221
260
|
|
|
222
261
|
DAxTA provides an interactive API workbench directly on your application.
|
|
@@ -245,6 +284,8 @@ Environment tokens only override keys that were actually recorded.
|
|
|
245
284
|
|
|
246
285
|
---
|
|
247
286
|
|
|
287
|
+
|
|
288
|
+
|
|
248
289
|
## DTO fields
|
|
249
290
|
|
|
250
291
|
Field metadata is derived from `class-validator` / `class-transformer` DTO metadata together with observed traffic.
|
|
@@ -260,6 +301,8 @@ This allows DAxTA to understand required and optional fields without another doc
|
|
|
260
301
|
|
|
261
302
|
---
|
|
262
303
|
|
|
304
|
+
|
|
305
|
+
|
|
263
306
|
## OpenAPI export
|
|
264
307
|
|
|
265
308
|
DAxTA is not limited to `/api-docs`.
|
|
@@ -288,25 +331,42 @@ Your tests remain the source of truth.
|
|
|
288
331
|
|
|
289
332
|
---
|
|
290
333
|
|
|
291
|
-
## `DAXTA_DOCS`
|
|
292
334
|
|
|
293
|
-
DAxTA requires an explicit decision about whether `/docs` should be mounted. Only `on` and `off` are accepted.
|
|
294
335
|
|
|
295
|
-
|
|
296
|
-
|
|
297
|
-
|
|
336
|
+
## When `/docs` is mounted
|
|
337
|
+
|
|
338
|
+
`apiDocs(app)` follows `NODE_ENV`, so the variable your application already sets decides it. There is no
|
|
339
|
+
DAxTA-specific flag to manage:
|
|
298
340
|
|
|
299
|
-
|
|
341
|
+
```bash
|
|
342
|
+
NODE_ENV=development pnpm start:dev # /docs mounted
|
|
343
|
+
NODE_ENV=dev # /docs mounted
|
|
344
|
+
NODE_ENV=test # /docs mounted
|
|
345
|
+
NODE_ENV=staging # /docs mounted
|
|
346
|
+
NODE_ENV=sta # /docs mounted
|
|
347
|
+
NODE_ENV=production # /docs not mounted
|
|
348
|
+
# NODE_ENV unset → /docs not mounted
|
|
300
349
|
```
|
|
301
350
|
|
|
302
|
-
|
|
351
|
+
The gate is closed by default: only `dev`, `development`, `test`, `sta` and `staging` open the docs. Anything
|
|
352
|
+
else — `production`, an unrecognised value, or no value at all — keeps them off, so a deployment that forgets to
|
|
353
|
+
set `NODE_ENV` never exposes them. `daxta install` adds `NODE_ENV=development` to your env file only when no env
|
|
354
|
+
file declares `NODE_ENV`; an existing value is yours and stays untouched.
|
|
355
|
+
|
|
356
|
+
Not mounting `/docs` does not remove `@t0.labs/daxta` from your Node image. It only skips the route.
|
|
303
357
|
|
|
304
|
-
|
|
358
|
+
The decision is exported if you need the same answer elsewhere:
|
|
359
|
+
|
|
360
|
+
```ts
|
|
361
|
+
import { docsEnabled } from '@t0.labs/daxta';
|
|
362
|
+
```
|
|
305
363
|
|
|
306
364
|
The path defaults to `/docs`. Override with `DAXTA_DOCS_PATH` or `docsPath` in `daxta.config.ts`.
|
|
307
365
|
|
|
308
366
|
---
|
|
309
367
|
|
|
368
|
+
|
|
369
|
+
|
|
310
370
|
## Commands
|
|
311
371
|
|
|
312
372
|
```bash
|
|
@@ -327,6 +387,8 @@ For most NestJS applications, `apiDocs(app)` is preferred over `daxta serve`.
|
|
|
327
387
|
|
|
328
388
|
---
|
|
329
389
|
|
|
390
|
+
|
|
391
|
+
|
|
330
392
|
## Sidebar order
|
|
331
393
|
|
|
332
394
|
```bash
|
|
@@ -358,6 +420,8 @@ daxta generate
|
|
|
358
420
|
|
|
359
421
|
---
|
|
360
422
|
|
|
423
|
+
|
|
424
|
+
|
|
361
425
|
## API
|
|
362
426
|
|
|
363
427
|
**NestJS** — only this belongs in `main.ts`:
|
|
@@ -378,7 +442,7 @@ import { apiDocsHandler } from '@t0.labs/daxta';
|
|
|
378
442
|
app.use(apiDocsHandler());
|
|
379
443
|
```
|
|
380
444
|
|
|
381
|
-
`apiDocs(app)` works on Express too — it is `app.use(apiDocsHandler())` plus the `
|
|
445
|
+
`apiDocs(app)` works on Express too — it is `app.use(apiDocsHandler())` plus the `NODE_ENV` gate.
|
|
382
446
|
|
|
383
447
|
**Standalone viewer** (CLI / rare):
|
|
384
448
|
|
|
@@ -390,6 +454,8 @@ serveApiDocs({ port: 5199 });
|
|
|
390
454
|
|
|
391
455
|
---
|
|
392
456
|
|
|
457
|
+
|
|
458
|
+
|
|
393
459
|
## The idea behind DAxTA
|
|
394
460
|
|
|
395
461
|
The idea is simple.
|
|
@@ -410,14 +476,16 @@ It is just trapped inside your tests.
|
|
|
410
476
|
|
|
411
477
|
**DAxTA turns it into something you can explore, execute, export, and share.**
|
|
412
478
|
|
|
413
|
-
|
|
479
|
+
**API Test → API Documentation**
|
|
414
480
|
|
|
415
|
-
|
|
481
|
+
You already wrote the tests. Let DAxTA write the docs.
|
|
416
482
|
|
|
417
483
|
---
|
|
418
484
|
|
|
485
|
+
|
|
486
|
+
|
|
419
487
|
## License
|
|
420
488
|
|
|
421
489
|
DAxTA is [MIT](LICENSE) licensed.
|
|
422
490
|
|
|
423
|
-
Copyright (c) 2026 t0.labs
|
|
491
|
+
Copyright (c) 2026 t0.labs
|