@t0.labs/daxta 0.4.0 → 0.4.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 +19 -18
- package/dist/cli/jest-hooks.d.ts +1 -1
- package/dist/cli/jest-hooks.js +127 -20
- package/package.json +9 -1
package/README.md
CHANGED
|
@@ -4,21 +4,19 @@
|
|
|
4
4
|
|
|
5
5
|
Swagger asks you to decorate controllers. DAxTA learns from what your tests actually call.
|
|
6
6
|
|
|
7
|
-
|
|
8
|
-
<img src="assets/readme/docs-overview.png" alt="DAxTA docs — recorded request, response, Try-it" width="920" />
|
|
9
|
-
</p>
|
|
7
|
+
DAxTA docs — recorded request, response, Try-it
|
|
10
8
|
|
|
11
9
|
## What you get
|
|
12
10
|
|
|
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
11
|
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
12
|
+
| After tests | On the app |
|
|
13
|
+
| ------------------------------------- | -------------------------------------------------------- |
|
|
14
|
+
| OpenAPI + HTML from real hits | `/docs` on the same port as Nest |
|
|
15
|
+
| Success / validation / auth scenarios | Send + Copy cURL from recorded calls |
|
|
16
|
+
| DTO field map (required vs optional) | `DAXTA_DOCS=true|false` gate (like Swagger’s prod check) |
|
|
17
|
+
|
|
18
|
+
|
|
19
|
+
Jest finishes — Docs ready on /docs
|
|
22
20
|
|
|
23
21
|
## How it works
|
|
24
22
|
|
|
@@ -37,7 +35,9 @@ Swagger asks you to decorate controllers. DAxTA learns from what your tests actu
|
|
|
37
35
|
|
|
38
36
|
1. **Install** attaches DAxTA as a Jest plugin (`setupFilesAfterEnv` + reporter). Your existing `test:integration` stays the entrypoint — DAxTA does not wrap the process.
|
|
39
37
|
2. **During the run** only traffic is recorded (disk flush). OpenAPI/HTML is built once when Jest finishes.
|
|
40
|
-
3.
|
|
38
|
+
3. `apiDocs(app)` in `main.ts` serves the generated viewer when `DAXTA_DOCS=true`.
|
|
39
|
+
|
|
40
|
+
|
|
41
41
|
|
|
42
42
|
## Install
|
|
43
43
|
|
|
@@ -60,19 +60,17 @@ pnpm run test:integration # Docs ready when Jest finishes
|
|
|
60
60
|
DAXTA_DOCS=true pnpm start:dev # open /docs on the app port
|
|
61
61
|
```
|
|
62
62
|
|
|
63
|
+
|
|
64
|
+
|
|
63
65
|
## Docs UI
|
|
64
66
|
|
|
65
67
|
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
68
|
|
|
67
|
-
|
|
68
|
-
<img src="assets/readme/docs-scenarios.png" alt="Scenario picker — success, validation, auth" width="920" />
|
|
69
|
-
</p>
|
|
69
|
+
Scenario picker — success, validation, auth
|
|
70
70
|
|
|
71
71
|
Field metadata comes from class-validator / class-transformer DTOs plus observed traffic:
|
|
72
72
|
|
|
73
|
-
|
|
74
|
-
<img src="assets/readme/docs-fields.png" alt="Required vs optional DTO fields" width="640" />
|
|
75
|
-
</p>
|
|
73
|
+
Required vs optional DTO fields
|
|
76
74
|
|
|
77
75
|
## `DAXTA_DOCS` (required)
|
|
78
76
|
|
|
@@ -97,6 +95,8 @@ daxta fields … # export field map for an operation
|
|
|
97
95
|
daxta call … # CLI Try-it
|
|
98
96
|
```
|
|
99
97
|
|
|
98
|
+
|
|
99
|
+
|
|
100
100
|
## API
|
|
101
101
|
|
|
102
102
|
```ts
|
|
@@ -106,3 +106,4 @@ apiDocs(app); // preferred — same origin as the API
|
|
|
106
106
|
app.use(apiDocsHandler()); // Express-style mount
|
|
107
107
|
serveApiDocs({ port: 5199 }); // standalone (CLI / rare)
|
|
108
108
|
```
|
|
109
|
+
|
package/dist/cli/jest-hooks.d.ts
CHANGED
|
@@ -6,7 +6,7 @@ export declare function resolveJestConfigPath(cwd: string, options: {
|
|
|
6
6
|
}): string | null;
|
|
7
7
|
/**
|
|
8
8
|
* Inject DAxTA as a Jest plugin (setup + reporter). Does not wrap the test process.
|
|
9
|
-
* Leaves
|
|
9
|
+
* Supports JSON and JS/CJS/MJS/TS config files. Leaves globalSetup / globalTeardown untouched.
|
|
10
10
|
*/
|
|
11
11
|
export declare function injectJestHooks(jestConfigPath: string, dryRun?: boolean): string[];
|
|
12
12
|
/** Restore package.json script if it was wrapped as `daxta test --yes`. */
|
package/dist/cli/jest-hooks.js
CHANGED
|
@@ -40,6 +40,8 @@ exports.unwrapDaxtaTestScript = unwrapDaxtaTestScript;
|
|
|
40
40
|
const fs_1 = require("fs");
|
|
41
41
|
const path = __importStar(require("path"));
|
|
42
42
|
const discover_test_1 = require("./discover-test");
|
|
43
|
+
const SETUP = '@t0.labs/daxta/setup';
|
|
44
|
+
const REPORTER = '@t0.labs/daxta/jest-reporter';
|
|
43
45
|
function loadJestJson(filePath) {
|
|
44
46
|
return JSON.parse((0, fs_1.readFileSync)(filePath, 'utf8'));
|
|
45
47
|
}
|
|
@@ -55,42 +57,147 @@ function resolveJestConfigPath(cwd, options) {
|
|
|
55
57
|
}
|
|
56
58
|
return null;
|
|
57
59
|
}
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
60
|
+
function isJsonConfigPath(filePath) {
|
|
61
|
+
return path.extname(filePath).toLowerCase() === '.json';
|
|
62
|
+
}
|
|
63
|
+
function isJsLikeConfigPath(filePath) {
|
|
64
|
+
return ['.js', '.cjs', '.mjs', '.ts', '.cts', '.mts'].includes(path.extname(filePath).toLowerCase());
|
|
65
|
+
}
|
|
66
|
+
/** Find `[`…`]` for `key: [` while skipping strings. */
|
|
67
|
+
function findArrayPropRange(source, key) {
|
|
68
|
+
const re = new RegExp(`${key}\\s*:\\s*\\[`);
|
|
69
|
+
const match = re.exec(source);
|
|
70
|
+
if (!match)
|
|
71
|
+
return null;
|
|
72
|
+
const open = match.index + match[0].length - 1;
|
|
73
|
+
let depth = 0;
|
|
74
|
+
let quote = null;
|
|
75
|
+
let escaped = false;
|
|
76
|
+
for (let i = open; i < source.length; i += 1) {
|
|
77
|
+
const ch = source[i];
|
|
78
|
+
if (quote) {
|
|
79
|
+
if (escaped) {
|
|
80
|
+
escaped = false;
|
|
81
|
+
continue;
|
|
82
|
+
}
|
|
83
|
+
if (ch === '\\' && quote !== '`') {
|
|
84
|
+
escaped = true;
|
|
85
|
+
continue;
|
|
86
|
+
}
|
|
87
|
+
if (ch === quote)
|
|
88
|
+
quote = null;
|
|
89
|
+
continue;
|
|
90
|
+
}
|
|
91
|
+
if (ch === '"' || ch === "'" || ch === '`') {
|
|
92
|
+
quote = ch;
|
|
93
|
+
continue;
|
|
94
|
+
}
|
|
95
|
+
if (ch === '[')
|
|
96
|
+
depth += 1;
|
|
97
|
+
else if (ch === ']') {
|
|
98
|
+
depth -= 1;
|
|
99
|
+
if (depth === 0)
|
|
100
|
+
return { open, close: i };
|
|
101
|
+
}
|
|
102
|
+
}
|
|
103
|
+
return null;
|
|
104
|
+
}
|
|
105
|
+
function insertIntoObjectLiteral(source, propertyLine) {
|
|
106
|
+
const anchors = [/module\.exports\s*=\s*\{/, /export\s+default\s+\{/, /exports\s*=\s*\{/];
|
|
107
|
+
for (const re of anchors) {
|
|
108
|
+
const match = re.exec(source);
|
|
109
|
+
if (!match)
|
|
110
|
+
continue;
|
|
111
|
+
const brace = match.index + match[0].length - 1;
|
|
112
|
+
return `${source.slice(0, brace + 1)}\n ${propertyLine}${source.slice(brace + 1)}`;
|
|
113
|
+
}
|
|
114
|
+
return null;
|
|
115
|
+
}
|
|
116
|
+
function injectIntoJsSource(source) {
|
|
63
117
|
const notes = [];
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
118
|
+
let next = source;
|
|
119
|
+
if (!next.includes(SETUP)) {
|
|
120
|
+
const range = findArrayPropRange(next, 'setupFilesAfterEnv');
|
|
121
|
+
if (range) {
|
|
122
|
+
const afterOpen = next.slice(range.open + 1);
|
|
123
|
+
const multiline = /^\s*\n/.test(afterOpen);
|
|
124
|
+
const insertion = multiline ? `\n '${SETUP}',` : `'${SETUP}', `;
|
|
125
|
+
next = `${next.slice(0, range.open + 1)}${insertion}${multiline ? afterOpen : afterOpen.trimStart()}`;
|
|
126
|
+
notes.push(`setupFilesAfterEnv += ${SETUP}`);
|
|
127
|
+
}
|
|
128
|
+
else {
|
|
129
|
+
const inserted = insertIntoObjectLiteral(next, `setupFilesAfterEnv: ['${SETUP}'],`);
|
|
130
|
+
if (!inserted) {
|
|
131
|
+
throw new Error('Could not find setupFilesAfterEnv or module.exports / export default object to inject DAxTA setup');
|
|
132
|
+
}
|
|
133
|
+
next = inserted;
|
|
134
|
+
notes.push(`setupFilesAfterEnv = [${SETUP}]`);
|
|
135
|
+
}
|
|
69
136
|
}
|
|
70
|
-
|
|
71
|
-
|
|
137
|
+
if (!next.includes(REPORTER)) {
|
|
138
|
+
const range = findArrayPropRange(next, 'reporters');
|
|
139
|
+
if (range) {
|
|
140
|
+
const beforeClose = next.slice(range.open + 1, range.close);
|
|
141
|
+
const needsComma = beforeClose.trim().length > 0 && !/,\s*$/.test(beforeClose.trim());
|
|
142
|
+
const injection = `${needsComma ? ',' : ''}\n '${REPORTER}',\n `;
|
|
143
|
+
next = `${next.slice(0, range.close)}${injection}${next.slice(range.close)}`;
|
|
144
|
+
notes.push(`reporters += ${REPORTER}`);
|
|
145
|
+
}
|
|
146
|
+
else {
|
|
147
|
+
const inserted = insertIntoObjectLiteral(next, `reporters: ['default', '${REPORTER}'],`);
|
|
148
|
+
if (!inserted) {
|
|
149
|
+
throw new Error('Could not find reporters or module.exports / export default object to inject DAxTA reporter');
|
|
150
|
+
}
|
|
151
|
+
next = inserted;
|
|
152
|
+
notes.push(`reporters = [default, ${REPORTER}]`);
|
|
153
|
+
}
|
|
72
154
|
}
|
|
155
|
+
return { source: next, notes };
|
|
156
|
+
}
|
|
157
|
+
function injectIntoJsonConfig(filePath, dryRun) {
|
|
158
|
+
const notes = [];
|
|
159
|
+
const data = loadJestJson(filePath);
|
|
73
160
|
const setup = Array.isArray(data.setupFilesAfterEnv) ? [...data.setupFilesAfterEnv] : [];
|
|
74
|
-
if (!setup.includes(
|
|
75
|
-
setup.unshift(
|
|
161
|
+
if (!setup.includes(SETUP)) {
|
|
162
|
+
setup.unshift(SETUP);
|
|
76
163
|
data.setupFilesAfterEnv = setup;
|
|
77
|
-
notes.push(
|
|
164
|
+
notes.push(`setupFilesAfterEnv += ${SETUP}`);
|
|
78
165
|
}
|
|
79
166
|
const reporters = Array.isArray(data.reporters) ? [...data.reporters] : ['default'];
|
|
80
167
|
const hasReporter = reporters.some((entry) => {
|
|
81
|
-
if (entry ===
|
|
168
|
+
if (entry === REPORTER)
|
|
82
169
|
return true;
|
|
83
|
-
if (Array.isArray(entry) && entry[0] ===
|
|
170
|
+
if (Array.isArray(entry) && entry[0] === REPORTER)
|
|
84
171
|
return true;
|
|
85
172
|
return false;
|
|
86
173
|
});
|
|
87
174
|
if (!hasReporter) {
|
|
88
|
-
reporters.push(
|
|
175
|
+
reporters.push(REPORTER);
|
|
89
176
|
data.reporters = reporters;
|
|
90
|
-
notes.push(
|
|
177
|
+
notes.push(`reporters += ${REPORTER}`);
|
|
91
178
|
}
|
|
92
179
|
if (!dryRun && notes.length) {
|
|
93
|
-
(0, fs_1.writeFileSync)(
|
|
180
|
+
(0, fs_1.writeFileSync)(filePath, `${JSON.stringify(data, null, 2)}\n`);
|
|
181
|
+
}
|
|
182
|
+
return notes;
|
|
183
|
+
}
|
|
184
|
+
/**
|
|
185
|
+
* Inject DAxTA as a Jest plugin (setup + reporter). Does not wrap the test process.
|
|
186
|
+
* Supports JSON and JS/CJS/MJS/TS config files. Leaves globalSetup / globalTeardown untouched.
|
|
187
|
+
*/
|
|
188
|
+
function injectJestHooks(jestConfigPath, dryRun = false) {
|
|
189
|
+
if (!(0, fs_1.existsSync)(jestConfigPath))
|
|
190
|
+
throw new Error(`Jest config not found: ${jestConfigPath}`);
|
|
191
|
+
if (isJsonConfigPath(jestConfigPath)) {
|
|
192
|
+
return injectIntoJsonConfig(jestConfigPath, dryRun);
|
|
193
|
+
}
|
|
194
|
+
if (!isJsLikeConfigPath(jestConfigPath)) {
|
|
195
|
+
throw new Error(`Unsupported Jest config type (${path.extname(jestConfigPath) || 'unknown'}). Use .json, .js, .cjs, .mjs, or .ts: ${jestConfigPath}`);
|
|
196
|
+
}
|
|
197
|
+
const original = (0, fs_1.readFileSync)(jestConfigPath, 'utf8');
|
|
198
|
+
const { source, notes } = injectIntoJsSource(original);
|
|
199
|
+
if (!dryRun && notes.length && source !== original) {
|
|
200
|
+
(0, fs_1.writeFileSync)(jestConfigPath, source);
|
|
94
201
|
}
|
|
95
202
|
return notes;
|
|
96
203
|
}
|
package/package.json
CHANGED
|
@@ -1,8 +1,16 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@t0.labs/daxta",
|
|
3
|
-
"version": "0.4.
|
|
3
|
+
"version": "0.4.2",
|
|
4
4
|
"description": "DAxTA \u2014 docs from Nest integration traffic + DTO field CLI / Try-it",
|
|
5
5
|
"license": "MIT",
|
|
6
|
+
"repository": {
|
|
7
|
+
"type": "git",
|
|
8
|
+
"url": "git+https://github.com/t0-labs/daxta.git"
|
|
9
|
+
},
|
|
10
|
+
"homepage": "https://github.com/t0-labs/daxta#readme",
|
|
11
|
+
"bugs": {
|
|
12
|
+
"url": "https://github.com/t0-labs/daxta/issues"
|
|
13
|
+
},
|
|
6
14
|
"main": "dist/index.js",
|
|
7
15
|
"types": "dist/index.d.ts",
|
|
8
16
|
"bin": {
|