@t0.labs/daxta 0.3.6 → 0.4.0
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 +80 -16
- package/assets/readme/demo.html +1896 -0
- package/assets/readme/docs-fields.png +0 -0
- package/assets/readme/docs-overview.png +0 -0
- package/assets/readme/docs-scenarios.png +0 -0
- package/assets/readme/terminal-docs-ready.png +0 -0
- package/dist/jest/reporter.d.ts +2 -5
- package/dist/jest/reporter.js +12 -27
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,8 +1,45 @@
|
|
|
1
|
-
#
|
|
1
|
+
# DAxTA
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
**Document API × Test API** — NestJS integration tests already hit your real endpoints. DAxTA records that traffic and turns it into living OpenAPI docs on your app port (`/docs`), with DTO required/optional fields and a Try-it workbench.
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
Swagger asks you to decorate controllers. DAxTA learns from what your tests actually call.
|
|
6
|
+
|
|
7
|
+
<p align="center">
|
|
8
|
+
<img src="assets/readme/docs-overview.png" alt="DAxTA docs — recorded request, response, Try-it" width="920" />
|
|
9
|
+
</p>
|
|
10
|
+
|
|
11
|
+
## What you get
|
|
12
|
+
|
|
13
|
+
| After tests | On the app |
|
|
14
|
+
| --- | --- |
|
|
15
|
+
| OpenAPI + HTML from real hits | `/docs` on the same port as Nest |
|
|
16
|
+
| Success / validation / auth scenarios | Send + Copy cURL from recorded calls |
|
|
17
|
+
| DTO field map (required vs optional) | `DAXTA_DOCS=true\|false` gate (like Swagger’s prod check) |
|
|
18
|
+
|
|
19
|
+
<p align="center">
|
|
20
|
+
<img src="assets/readme/terminal-docs-ready.png" alt="Jest finishes — Docs ready on /docs" width="720" />
|
|
21
|
+
</p>
|
|
22
|
+
|
|
23
|
+
## How it works
|
|
24
|
+
|
|
25
|
+
```text
|
|
26
|
+
your Jest suite
|
|
27
|
+
│ supertest / superagent hits
|
|
28
|
+
▼
|
|
29
|
+
DAxTA records hits to disk
|
|
30
|
+
│ (no OpenAPI rebuild mid-run)
|
|
31
|
+
▼
|
|
32
|
+
onRunComplete → one full build
|
|
33
|
+
│
|
|
34
|
+
▼
|
|
35
|
+
Docs ready → http://localhost:3000/docs
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
1. **Install** attaches DAxTA as a Jest plugin (`setupFilesAfterEnv` + reporter). Your existing `test:integration` stays the entrypoint — DAxTA does not wrap the process.
|
|
39
|
+
2. **During the run** only traffic is recorded (disk flush). OpenAPI/HTML is built once when Jest finishes.
|
|
40
|
+
3. **`apiDocs(app)`** in `main.ts` serves the generated viewer when `DAXTA_DOCS=true`.
|
|
41
|
+
|
|
42
|
+
## Install
|
|
6
43
|
|
|
7
44
|
```bash
|
|
8
45
|
pnpm dlx @t0.labs/daxta install
|
|
@@ -10,27 +47,54 @@ pnpm dlx @t0.labs/daxta install
|
|
|
10
47
|
npx @t0.labs/daxta install
|
|
11
48
|
```
|
|
12
49
|
|
|
13
|
-
|
|
14
|
-
Your `test:integration` (or whatever you pick) stays the entrypoint — DAxTA does **not** wrap the process.
|
|
50
|
+
Wires `apiDocs(app)` into your Nest entry and hooks Jest. Then:
|
|
15
51
|
|
|
16
52
|
```ts
|
|
17
53
|
import { apiDocs } from '@t0.labs/daxta';
|
|
18
|
-
|
|
54
|
+
|
|
55
|
+
apiDocs(app); // requires DAXTA_DOCS in the environment
|
|
19
56
|
```
|
|
20
57
|
|
|
21
|
-
|
|
58
|
+
```bash
|
|
59
|
+
pnpm run test:integration # Docs ready when Jest finishes
|
|
60
|
+
DAXTA_DOCS=true pnpm start:dev # open /docs on the app port
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
## Docs UI
|
|
64
|
+
|
|
65
|
+
Recorded scenarios (success, validation, missing auth) stay tied to the request that produced them — headers included. Empty auth on a 401 scenario stays empty; env tokens only override keys that were actually recorded.
|
|
66
|
+
|
|
67
|
+
<p align="center">
|
|
68
|
+
<img src="assets/readme/docs-scenarios.png" alt="Scenario picker — success, validation, auth" width="920" />
|
|
69
|
+
</p>
|
|
70
|
+
|
|
71
|
+
Field metadata comes from class-validator / class-transformer DTOs plus observed traffic:
|
|
72
|
+
|
|
73
|
+
<p align="center">
|
|
74
|
+
<img src="assets/readme/docs-fields.png" alt="Required vs optional DTO fields" width="640" />
|
|
75
|
+
</p>
|
|
76
|
+
|
|
77
|
+
## `DAXTA_DOCS` (required)
|
|
78
|
+
|
|
79
|
+
Same idea as Nest Swagger’s “don’t call `setup` in prod”:
|
|
22
80
|
|
|
23
81
|
```bash
|
|
24
|
-
DAXTA_DOCS=true #
|
|
25
|
-
DAXTA_DOCS=false #
|
|
82
|
+
DAXTA_DOCS=true # mount /docs
|
|
83
|
+
DAXTA_DOCS=false # no-op (must still be set)
|
|
84
|
+
# unset / empty → throws — make the choice explicit
|
|
26
85
|
```
|
|
27
86
|
|
|
28
|
-
|
|
87
|
+
`false` does not remove `@t0.labs/daxta` from the Node image; it only skips mounting `/docs`.
|
|
88
|
+
|
|
89
|
+
## Commands
|
|
29
90
|
|
|
30
91
|
```bash
|
|
31
|
-
|
|
32
|
-
daxta migrate
|
|
33
|
-
daxta
|
|
92
|
+
daxta install # one-shot setup
|
|
93
|
+
daxta migrate # after a package bump
|
|
94
|
+
daxta build # rebuild OpenAPI/HTML from recorded hits
|
|
95
|
+
daxta serve # optional standalone viewer (prefer apiDocs on the app)
|
|
96
|
+
daxta fields … # export field map for an operation
|
|
97
|
+
daxta call … # CLI Try-it
|
|
34
98
|
```
|
|
35
99
|
|
|
36
100
|
## API
|
|
@@ -38,7 +102,7 @@ daxta serve # standalone viewer (optional)
|
|
|
38
102
|
```ts
|
|
39
103
|
import { apiDocs, apiDocsHandler, serveApiDocs } from '@t0.labs/daxta';
|
|
40
104
|
|
|
41
|
-
apiDocs(app);
|
|
42
|
-
app.use(apiDocsHandler());
|
|
43
|
-
serveApiDocs({ port: 5199 });
|
|
105
|
+
apiDocs(app); // preferred — same origin as the API
|
|
106
|
+
app.use(apiDocsHandler()); // Express-style mount
|
|
107
|
+
serveApiDocs({ port: 5199 }); // standalone (CLI / rare)
|
|
44
108
|
```
|