tolkira 0.2.0 → 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/DESIGN.md +131 -9
- package/GLOSSARY.md +201 -1
- package/README.md +413 -29
- package/SECURITY.md +3 -0
- package/dist/attachment.d.ts +33 -0
- package/dist/attempt-diagnostics.d.ts +2 -0
- package/dist/ci.d.ts +12 -0
- package/dist/cli.js +6881 -2691
- package/dist/cli.js.map +4 -4
- package/dist/compat/cucumber-html-reporter.cjs +12 -0
- package/dist/compat/cucumber-html-reporter.d.cts +10 -0
- package/dist/compat/cucumber-html-reporter.js +263 -26
- package/dist/compat/cucumber-html-reporter.js.map +4 -4
- package/dist/compat/options.d.ts +4 -0
- package/dist/email.d.ts +18 -0
- package/dist/history.d.ts +41 -0
- package/dist/i18n/catalogs.d.ts +7 -0
- package/dist/index.d.ts +15 -7
- package/dist/index.js +5301 -1709
- package/dist/index.js.map +4 -4
- package/dist/input/background.d.ts +4 -0
- package/dist/input/detect.d.ts +30 -0
- package/dist/input/load.d.ts +3 -0
- package/dist/input/playwright.d.ts +14 -0
- package/dist/options.d.ts +18 -0
- package/dist/output.d.ts +9 -1
- package/dist/pdf.d.ts +9 -0
- package/dist/render/ansi.d.ts +2 -0
- package/dist/render/attachments.d.ts +3 -0
- package/dist/render/ci.d.ts +4 -0
- package/dist/render/client-bundle.d.ts +1 -0
- package/dist/render/client-i18n.d.ts +7 -0
- package/dist/render/details.d.ts +5 -0
- package/dist/render/dom-contract.d.ts +42 -0
- package/dist/render/format.d.ts +34 -0
- package/dist/render/html.d.ts +2 -9
- package/dist/render/i18n.d.ts +30 -0
- package/dist/render/markdown.d.ts +2 -0
- package/dist/render/matrix.d.ts +3 -0
- package/dist/render/print-script.d.ts +1 -0
- package/dist/render/report-client.d.ts +1 -0
- package/dist/render/report.d.ts +4 -0
- package/dist/render/search.d.ts +21 -0
- package/dist/render/trends.d.ts +7 -0
- package/dist/render/triage.d.ts +5 -0
- package/dist/render/types.d.ts +26 -0
- package/dist/report/index-run.d.ts +69 -0
- package/dist/report/model.d.ts +96 -6
- package/dist/report/status.d.ts +12 -0
- package/dist/stream.d.ts +15 -0
- package/dist/summary.d.ts +17 -2
- package/dist/text.d.ts +15 -0
- package/dist/warnings.d.ts +6 -0
- package/docs/AGENT-INTERFACE.md +504 -33
- package/docs/CI.md +185 -0
- package/docs/COMPATIBILITY.md +121 -16
- package/docs/CUCUMBER-COMPATIBILITY.md +232 -15
- package/docs/EMAIL.md +273 -0
- package/docs/I18N.md +241 -0
- package/docs/JUNIT-XML.md +46 -4
- package/docs/LIMITATIONS.md +21 -0
- package/docs/PDF.md +255 -0
- package/llms.txt +63 -0
- package/package.json +46 -8
package/README.md
CHANGED
|
@@ -1,12 +1,14 @@
|
|
|
1
1
|
# Tolkira
|
|
2
2
|
|
|
3
|
-
**Cucumber reports that stay readable: legacy JSON, Messages
|
|
3
|
+
**Cucumber reports that stay readable: legacy JSON, Messages, JUnit XML and Playwright JSON in one self-contained HTML file.**
|
|
4
4
|
|
|
5
5
|
Tolkira turns test results into a single HTML file you can open offline, attach
|
|
6
6
|
to a ticket, or keep as a CI artifact. Screenshots, logs and other attachments
|
|
7
|
-
|
|
7
|
+
are embedded where available; the report names any it had to skip. There is no
|
|
8
|
+
server, no CDN and no telemetry. An opt-in PDF export reuses the same print view
|
|
9
|
+
when the optional Playwright Chromium engine is installed.
|
|
8
10
|
|
|
9
|
-
Current release: **v0.
|
|
11
|
+
Current release: **v0.4.0** - [npm](https://www.npmjs.com/package/tolkira) - [Changelog](https://github.com/Silasoa/tolkira/blob/main/docs/CHANGELOG.md)
|
|
10
12
|
|
|
11
13
|
> **How this is built:** Tolkira is human-directed and largely AI-generated.
|
|
12
14
|
> The maintainer sets the product direction and approves releases. Most code,
|
|
@@ -18,17 +20,23 @@ Current release: **v0.2.0** · [npm](https://www.npmjs.com/package/tolkira) · [
|
|
|
18
20
|
|
|
19
21
|
## Install
|
|
20
22
|
|
|
23
|
+
Tolkira requires Node.js 22 or newer.
|
|
24
|
+
|
|
21
25
|
```shell
|
|
26
|
+
# CLI for one-off use
|
|
22
27
|
npm install --global tolkira
|
|
23
28
|
tolkira --help
|
|
24
29
|
```
|
|
25
30
|
|
|
26
|
-
Or
|
|
31
|
+
Or add it to a project and run it from there (recommended for CI):
|
|
27
32
|
|
|
28
33
|
```shell
|
|
34
|
+
npm install --save-dev tolkira
|
|
29
35
|
npx tolkira --help
|
|
30
36
|
```
|
|
31
37
|
|
|
38
|
+
`npx tolkira --help` also works without a local install.
|
|
39
|
+
|
|
32
40
|
On Windows, `npx` can fail when the current folder contains parentheses in its
|
|
33
41
|
path. Use the global install or a folder without parentheses if that happens.
|
|
34
42
|
|
|
@@ -47,19 +55,207 @@ tolkira test-results/ --out report.html \
|
|
|
47
55
|
|
|
48
56
|
# Embed a logo (PNG, JPEG, GIF, WebP or SVG)
|
|
49
57
|
tolkira test-results/ --out report.html --logo path/to/logo.png
|
|
58
|
+
|
|
59
|
+
# Keep aggregate run history and show a Trends tab from the second run
|
|
60
|
+
tolkira test-results/ --out report.html --history .history/history.json
|
|
61
|
+
|
|
62
|
+
# German report UI; test data stays verbatim
|
|
63
|
+
tolkira test-results/ --out report.html --locale de
|
|
64
|
+
|
|
65
|
+
# Write a small HTML email body beside the report (no sending)
|
|
66
|
+
tolkira test-results/ --out report.html --email email.html
|
|
67
|
+
|
|
68
|
+
# Print an A4 PDF (needs the optional Playwright engine; see below)
|
|
69
|
+
tolkira test-results/ --out report.html --pdf report.pdf
|
|
50
70
|
```
|
|
51
71
|
|
|
52
72
|
Tolkira accepts one or more files and directories. A directory is scanned
|
|
53
73
|
recursively for supported result files. Everything is merged into one report.
|
|
74
|
+
The optional history file is a separate sidecar: without `--history` no history
|
|
75
|
+
is read or written and the report stays one file. Use one sidecar per suite and
|
|
76
|
+
variant; mixing runs makes the trend meaningless. The Trends tab needs
|
|
77
|
+
JavaScript: a copy opened without JavaScript shows the Report view and an inert
|
|
78
|
+
tab. Printing works in both cases; see
|
|
79
|
+
[Print or Save as PDF](#print-or-save-as-pdf).
|
|
80
|
+
|
|
81
|
+
## Print or Save as PDF
|
|
82
|
+
|
|
83
|
+
Use the browser's print dialog and choose **Save as PDF** as the destination.
|
|
84
|
+
With JavaScript, printing captures the whole text and screenshot archive: the
|
|
85
|
+
Report, Details and (when history is present) Trends views, with every closed
|
|
86
|
+
feature and scenario opened and lazy thumbnails requested eagerly. The current
|
|
87
|
+
search and filter state carries into print, so clear it first to archive the
|
|
88
|
+
whole run. The active tab is left untouched; previously closed details, the
|
|
89
|
+
lightbox and the scroll lock return in browsers that fire `afterprint`; the
|
|
90
|
+
print-only panel reveal is scoped to print media, so a missed `afterprint`
|
|
91
|
+
cannot stack panels on screen. The interactive chrome (tabs, toolbar, filters,
|
|
92
|
+
copy and expand buttons) is hidden, the page uses the light palette even when
|
|
93
|
+
the screen is dark, and the tables are sized to the printable width.
|
|
94
|
+
|
|
95
|
+
- **Failures-only Report:** press **Failed only**, then print. This is still an
|
|
96
|
+
archival print, not the concise summary: the Report view keeps only the
|
|
97
|
+
filtered rows and adds a visible count marker, while Details and Trends print
|
|
98
|
+
in full. The concise email summary is available with `--email`.
|
|
99
|
+
- **Without JavaScript:** the active Report view prints with the chrome hidden;
|
|
100
|
+
Details and Trends stay hidden and closed features stay closed. Without
|
|
101
|
+
`beforeprint` support the same fallback applies.
|
|
102
|
+
- **Wide runs:** if an unusually wide matrix still clips at the right edge,
|
|
103
|
+
choose **Landscape** in the print dialog.
|
|
104
|
+
- **Browser headers and footers:** the browser's own header/footer, page numbers
|
|
105
|
+
and URL are not part of the report. Turn them off for a shared PDF, because
|
|
106
|
+
the footer can reveal a local file path or URL; with them off, pages after the
|
|
107
|
+
first carry no report title or page number, because a repeated print title is
|
|
108
|
+
not implemented (see [Limitations](docs/LIMITATIONS.md)).
|
|
109
|
+
- **Video and audio** attachments cannot print, so the print is a text and
|
|
110
|
+
screenshot archive, not a full attachment copy; screenshots, text attachments
|
|
111
|
+
and the skipped-attachment notice do print.
|
|
112
|
+
|
|
113
|
+
Browser printing needs no network, no extra tool and no PDF engine. There is no
|
|
114
|
+
mail delivery and no print button: `--email` writes a separate HTML mail body,
|
|
115
|
+
and the browser's print command is the zero-install PDF route.
|
|
116
|
+
|
|
117
|
+
### PDF file with `--pdf`
|
|
118
|
+
|
|
119
|
+
For CI and headless workflows, `--pdf <file>` prints the same complete archive
|
|
120
|
+
without a print dialog. Install the optional engine in the project where Tolkira
|
|
121
|
+
runs; a project-local Tolkira install is recommended:
|
|
122
|
+
|
|
123
|
+
```shell
|
|
124
|
+
npm i -D playwright-core@^1.65.0
|
|
125
|
+
npx playwright-core install chromium-headless-shell
|
|
126
|
+
tolkira test-results/ --out report.html --pdf report.pdf
|
|
127
|
+
```
|
|
54
128
|
|
|
55
|
-
|
|
56
|
-
the
|
|
129
|
+
The PDF is the full rendered archive, not a one-page executive summary; use
|
|
130
|
+
`--email` for the concise summary. It is A4 portrait with 12 mm margins, no
|
|
131
|
+
browser header/footer or page numbers, and it follows the report locale. Letter
|
|
132
|
+
and custom paper are not exposed. It is Chromium-only, has no CLI filter state,
|
|
133
|
+
does not print video/audio, and `--logo`/`--history` still require `--out`.
|
|
134
|
+
`--pdf-timeout <ms>` overrides the five-minute render deadline. The optional
|
|
135
|
+
engine is a dynamic import resolved beside Tolkira or in the project: the default
|
|
136
|
+
install and runtime dependency surface, report, JSON and CI bytes are unchanged.
|
|
137
|
+
The write order is report → PDF → email → history → `--ci-out` → stdout, so a PDF
|
|
138
|
+
failure exits 1, keeps the report and skips later outputs. Common HTML reporters
|
|
139
|
+
ship no PDF export, and Allure exports CSV; Playwright/CI teams already print
|
|
140
|
+
through headless Chromium, which is the same engine route. See
|
|
141
|
+
[PDF export](docs/PDF.md) for the install, API, costs and limits.
|
|
142
|
+
|
|
143
|
+
## For agents and CI
|
|
144
|
+
|
|
145
|
+
Install as a project dependency and write the report, the optional email body
|
|
146
|
+
and the JSON summary:
|
|
57
147
|
|
|
58
148
|
```shell
|
|
59
|
-
|
|
60
|
-
tolkira test-results/ --json
|
|
149
|
+
npm install --save-dev tolkira
|
|
150
|
+
npx tolkira test-results/ --out report.html --email email.html --title "CI run" --json > summary.json
|
|
151
|
+
```
|
|
152
|
+
|
|
153
|
+
GitHub Actions step:
|
|
154
|
+
|
|
155
|
+
```yaml
|
|
156
|
+
- name: Generate Cucumber report
|
|
157
|
+
if: always()
|
|
158
|
+
run: npx tolkira test-results/ --out report.html --email email.html --history .history/history.json --title "CI run" --json > summary.json
|
|
159
|
+
|
|
160
|
+
- name: Upload report
|
|
161
|
+
if: always()
|
|
162
|
+
uses: actions/upload-artifact@v4
|
|
163
|
+
with:
|
|
164
|
+
name: cucumber-report
|
|
165
|
+
include-hidden-files: true
|
|
166
|
+
path: |
|
|
167
|
+
report.html
|
|
168
|
+
email.html
|
|
169
|
+
summary.json
|
|
170
|
+
.history/history.json
|
|
171
|
+
```
|
|
172
|
+
|
|
173
|
+
`email.html` is an optional, small HTML mail body; a later CI mail step can use
|
|
174
|
+
it as `html_body` and attach `report.html`. Tolkira never sends mail and exits 0
|
|
175
|
+
even when tests fail, so derive the subject from `summary.json` (`jq -r .status`),
|
|
176
|
+
not from the job status. See [Email summary](docs/EMAIL.md).
|
|
177
|
+
|
|
178
|
+
Add `--pdf report.pdf` to the same command for a print archive. It needs the
|
|
179
|
+
optional engine in the project (`npm i -D playwright-core@^1.65.0 &&
|
|
180
|
+
npx playwright-core install chromium-headless-shell`) and composes with
|
|
181
|
+
`--out`, `--email`, `--history`, `--json` and `--ci`; see
|
|
182
|
+
[PDF export](docs/PDF.md). The PDF is written after the report and before the
|
|
183
|
+
email, so a PDF failure keeps `report.html` and skips the later outputs.
|
|
184
|
+
|
|
185
|
+
Persist `.history/history.json` between CI runs (for example with
|
|
186
|
+
`actions/cache`) so the next run continues the trend. A missing sidecar starts a
|
|
187
|
+
new history; upload it beside the report if you want another job to continue it.
|
|
188
|
+
|
|
189
|
+
`--json` writes exactly one JSON document to stdout; warnings go to stderr.
|
|
190
|
+
Exit code 0 means the report was generated, not that the tests passed. Read
|
|
191
|
+
`status` and `counts` from the summary. Abridged real output (counts and steps
|
|
192
|
+
trimmed):
|
|
193
|
+
|
|
194
|
+
```json
|
|
195
|
+
{
|
|
196
|
+
"schemaVersion": 2,
|
|
197
|
+
"status": "failed",
|
|
198
|
+
"counts": {
|
|
199
|
+
"scenarios": { "total": 6, "passed": 5, "failed": 1 }
|
|
200
|
+
},
|
|
201
|
+
"scenarios": [
|
|
202
|
+
{
|
|
203
|
+
"name": "Fred wants to see passing scenarios in the HTML report",
|
|
204
|
+
"uri": "features/happy.feature",
|
|
205
|
+
"status": "failed",
|
|
206
|
+
"executed": true,
|
|
207
|
+
"steps": [
|
|
208
|
+
{
|
|
209
|
+
"keyword": "When",
|
|
210
|
+
"text": "this feature runs with background",
|
|
211
|
+
"status": "failed",
|
|
212
|
+
"message": "Expected values to be strictly equal: -8 !== 0"
|
|
213
|
+
}
|
|
214
|
+
]
|
|
215
|
+
}
|
|
216
|
+
]
|
|
217
|
+
}
|
|
61
218
|
```
|
|
62
219
|
|
|
220
|
+
Paste this into an agent's instructions:
|
|
221
|
+
|
|
222
|
+
```text
|
|
223
|
+
Use Tolkira for Cucumber results. Run `npx tolkira <inputs> --out report.html --json`
|
|
224
|
+
and parse stdout as the JSON summary; do not scrape the HTML. Exit code 0 means
|
|
225
|
+
the report was generated, not that the tests passed. Read summary.status and
|
|
226
|
+
summary.counts, and check scenarios[].executed before treating a status as an
|
|
227
|
+
outcome. Upload report.html as the human-facing artifact.
|
|
228
|
+
```
|
|
229
|
+
|
|
230
|
+
See [`docs/AGENT-INTERFACE.md`](https://github.com/Silasoa/tolkira/blob/main/docs/AGENT-INTERFACE.md)
|
|
231
|
+
for the full schema and exit codes.
|
|
232
|
+
|
|
233
|
+
### CI annotations and step summaries
|
|
234
|
+
|
|
235
|
+
GitHub turns Tolkira's workflow commands into annotations without `--out`:
|
|
236
|
+
|
|
237
|
+
```shell
|
|
238
|
+
npx tolkira test-results/ --ci github
|
|
239
|
+
```
|
|
240
|
+
|
|
241
|
+
For a GitHub step summary, append Markdown so earlier steps survive:
|
|
242
|
+
|
|
243
|
+
```shell
|
|
244
|
+
npx tolkira test-results/ --ci markdown >> "$GITHUB_STEP_SUMMARY"
|
|
245
|
+
```
|
|
246
|
+
|
|
247
|
+
GitLab and other CI systems can keep the Markdown as a file:
|
|
248
|
+
|
|
249
|
+
```shell
|
|
250
|
+
npx tolkira test-results/ --out report.html --ci markdown --ci-out tolkira-summary.md
|
|
251
|
+
```
|
|
252
|
+
|
|
253
|
+
`--ci github` writes to stdout only; `--ci-out` requires `--ci markdown`, is
|
|
254
|
+
written atomically and must not overwrite an input, the logo or `--out`. Exit
|
|
255
|
+
codes do not change: a failed test run still exits 0. See
|
|
256
|
+
[`docs/CI.md`](https://github.com/Silasoa/tolkira/blob/main/docs/CI.md) for the
|
|
257
|
+
GitHub and GitLab examples, output caps and the unredacted-message warning.
|
|
258
|
+
|
|
63
259
|
## What you get
|
|
64
260
|
|
|
65
261
|
- **One file that works offline.** CSS, JavaScript and attachments are inline.
|
|
@@ -69,23 +265,52 @@ tolkira test-results/ --json
|
|
|
69
265
|
with links that open the scenario detail.
|
|
70
266
|
- **Multi-file context.** A source strip shows per-input status, counts and a
|
|
71
267
|
proportion bar when the run has more than one input file and provenance is
|
|
72
|
-
unambiguous.
|
|
73
|
-
source.
|
|
268
|
+
unambiguous. It is hidden at 560 px or narrower, and the Report row hides its
|
|
269
|
+
source at 900 px or narrower; the Details matrix keeps the source label.
|
|
74
270
|
- **Screenshots and attachments that survive.** Images, text, video, audio and
|
|
75
|
-
files are preserved through the
|
|
271
|
+
files are preserved through the input adapters where available; skipped path
|
|
272
|
+
attachments are named in the report.
|
|
76
273
|
- **Search and filters.** Search scenarios, features, steps and tags; filter by
|
|
77
|
-
status and tag;
|
|
274
|
+
status and tag; a `Failed only` preset hides other statuses and unexecuted
|
|
275
|
+
rows; open matching features automatically and highlight matches.
|
|
276
|
+
- **Rendered descriptions.** Feature, rule, background, scenario and examples
|
|
277
|
+
descriptions render a safe GFM subset - headings, emphasis, code, lists,
|
|
278
|
+
tables, quotes and http(s)/mailto links - from Messages, legacy JSON, JUnit
|
|
279
|
+
and Playwright JSON.
|
|
280
|
+
- **Tag expressions.** Search accepts the official Cucumber grammar
|
|
281
|
+
(`@a and not @b`, parentheses, escaped tags). Mixed text and tags fall back to
|
|
282
|
+
plain substring search.
|
|
283
|
+
- **Shareable filtered views.** Search, hidden statuses (including the failed-only
|
|
284
|
+
preset's `hide=unexecuted`) and the tag filter live in `?query=`, repeated
|
|
285
|
+
`?hide=` and `?tag=`, so a URL reproduces the same view.
|
|
286
|
+
- **Parameter highlighting.** Matched step arguments render with their Cucumber
|
|
287
|
+
parameter type from Messages; ambiguous or unmatched steps stay plain.
|
|
288
|
+
- **Messages stream adapter.** `CucumberHtmlStream` is shape-compatible with the
|
|
289
|
+
official formatter: it accepts envelopes, buffers until flush and emits the
|
|
290
|
+
same offline HTML as `renderReport`, for embedding without a temp file.
|
|
78
291
|
- **Copy failure.** Copy a failed scenario's feature, failed step and error as
|
|
79
292
|
plain text for a ticket or an agent.
|
|
80
293
|
- **A Details view when you need it.** Status distribution, a feature-by-status
|
|
81
|
-
matrix, run metadata and the
|
|
294
|
+
matrix, run metadata and the Run environment (producer, runtime, OS, CPU,
|
|
82
295
|
protocol).
|
|
296
|
+
- **Opt-in run trends.** `--history <file>` keeps the last 30 aggregate runs and
|
|
297
|
+
adds a Trends tab from the second run: a newest-first table and a pass-rate
|
|
298
|
+
sparkline. The sidecar holds counts, status, the resolved title, duration and
|
|
299
|
+
attachment totals only, never scenario names or paths; a report embeds the runs
|
|
300
|
+
it was generated with, so share it with that in mind.
|
|
83
301
|
- **A stable summary for agents.** `--json` and `summarizeReport()` return a
|
|
84
302
|
versioned schema with counts, durations, scenarios, steps and failure
|
|
85
303
|
messages.
|
|
86
304
|
- **Accessible by default.** Keyboard navigation, visible focus, text status
|
|
87
305
|
labels as well as colour, dark mode and 200% zoom reflow. Accessibility is an
|
|
88
306
|
ongoing effort; feedback is welcome.
|
|
307
|
+
- **Report language.** `--locale de` renders the report shell, labels and
|
|
308
|
+
accessibility text in German; `de-AT` keeps the regional tag and uses the
|
|
309
|
+
German catalog. Test data, Gherkin keywords, attachment content and names,
|
|
310
|
+
metadata and URIs render unchanged in every locale; the JSON summary stays
|
|
311
|
+
English. English is the default; one report is one locale and there is no
|
|
312
|
+
in-report switcher. See
|
|
313
|
+
[docs/I18N.md](https://github.com/Silasoa/tolkira/blob/main/docs/I18N.md).
|
|
89
314
|
- **Your branding.** Title, metadata, logo and accent colour without forking the
|
|
90
315
|
shell.
|
|
91
316
|
|
|
@@ -93,14 +318,16 @@ tolkira test-results/ --json
|
|
|
93
318
|
|
|
94
319
|
| Input | What works |
|
|
95
320
|
| --- | --- |
|
|
96
|
-
| **Legacy Cucumber JSON** | cucumber-js 2.3.1–13.3.0, Behave 1.3.3, cucumber-jvm 7.22.1 and cucumber-ruby 12.0.1 are
|
|
321
|
+
| **Legacy Cucumber JSON** | cucumber-js 2.3.1–13.3.0, Behave 1.3.3, cucumber-jvm 7.22.1 and cucumber-ruby 12.0.1 are covered by producer fixtures. Behave's real run includes statuses, durations, a multiline doc string, a data table, an inline PNG, a multiline error message and an `error` status; see the [dated limitations table](https://github.com/Silasoa/tolkira/blob/main/docs/LIMITATIONS.md). Other producers often work; the adapter follows the Cucumber legacy dialect. |
|
|
97
322
|
| **Cucumber Messages (NDJSON)** | cucumber-js 11.2, cucumber-jvm 7.22.1 and cucumber-ruby 12.0.1 fixtures. This is the modern, implementation-independent format. |
|
|
98
323
|
| **JUnit XML** | Basic mode: suites, test cases, statuses, durations, failures, skipped cases and system output. JUnit has no Gherkin steps or screenshots; each test case is shown as one synthetic step. |
|
|
324
|
+
| **Playwright JSON** | Native adapter for the Playwright JSON reporter: projects, file/describe rules, retries (the final attempt is visible), nested steps, expected/unexpected outcomes, tags, annotations, inline and in-tree path attachments, `stdout`/`stderr` and run-level errors. No trace viewer or HTML-report replay. |
|
|
99
325
|
|
|
100
326
|
Multiple files and mixed formats can be merged into one run. See
|
|
101
327
|
[`docs/CUCUMBER-COMPATIBILITY.md`](https://github.com/Silasoa/tolkira/blob/main/docs/CUCUMBER-COMPATIBILITY.md) for the
|
|
102
|
-
tested producer matrix
|
|
103
|
-
[`docs/JUNIT-XML.md`](https://github.com/Silasoa/tolkira/blob/main/docs/JUNIT-XML.md) for the JUnit limits
|
|
328
|
+
tested producer matrix,
|
|
329
|
+
[`docs/JUNIT-XML.md`](https://github.com/Silasoa/tolkira/blob/main/docs/JUNIT-XML.md) for the JUnit limits and
|
|
330
|
+
[`docs/PLAYWRIGHT-JSON.md`](https://github.com/Silasoa/tolkira/blob/main/docs/PLAYWRIGHT-JSON.md) for the Playwright mapping.
|
|
104
331
|
|
|
105
332
|
## Why Tolkira exists
|
|
106
333
|
|
|
@@ -113,9 +340,9 @@ work offline lose their layout and charts.
|
|
|
113
340
|
Tolkira keeps the old input working and fixes the parts that hurt:
|
|
114
341
|
|
|
115
342
|
- one offline file instead of CDN dependencies;
|
|
116
|
-
- legacy JSON
|
|
343
|
+
- legacy JSON, modern Messages and native Playwright JSON;
|
|
117
344
|
- JUnit XML as cheap breadth for non-Cucumber teams;
|
|
118
|
-
- screenshots and attachments
|
|
345
|
+
- screenshots and attachments embedded where available;
|
|
119
346
|
- a stable JSON summary for agents and CI;
|
|
120
347
|
- a small, reviewed dependency surface.
|
|
121
348
|
|
|
@@ -124,6 +351,28 @@ can produce one file. Tolkira's difference is the combination - both Cucumber
|
|
|
124
351
|
generations, JUnit as cheap breadth, an agent-readable summary, and no server,
|
|
125
352
|
CDN or telemetry.
|
|
126
353
|
|
|
354
|
+
### What parity means here
|
|
355
|
+
|
|
356
|
+
"Parity" in this project means content and navigation: the same statements,
|
|
357
|
+
steps, tags, statuses, durations and descriptions, plus search, tag expressions
|
|
358
|
+
and shareable filter URLs, whether the input is legacy JSON, Messages, JUnit or
|
|
359
|
+
Playwright JSON.
|
|
360
|
+
It does not mean theme parity with `cucumber-html-reporter`, a report folder, or
|
|
361
|
+
external attachments; Tolkira deliberately stays one offline file. The honest
|
|
362
|
+
claim is credible Messages report parity, not full formatter parity.
|
|
363
|
+
|
|
364
|
+
### How it compares
|
|
365
|
+
|
|
366
|
+
Last checked 2026-11-20 against the current package docs. Trade-offs are
|
|
367
|
+
deliberate; pick the tool that fits the job.
|
|
368
|
+
|
|
369
|
+
| Tool | Offline | Legacy JSON | Messages | JUnit | Playwright JSON | JSON summary | Themes | ESM/CJS | Node | Maintenance | Choose it if… |
|
|
370
|
+
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
|
|
371
|
+
| [cucumber-html-reporter](https://github.com/gkushang/cucumber-html-reporter) | No, CDN assets | Yes | No | No | No | No | Three built-in themes | CJS | Old, no engine pin | Unmaintained since Oct 2024 | You need its exact themes and offline use is not a requirement. |
|
|
372
|
+
| [multiple-cucumber-html-reporter](https://github.com/WasiqB/multiple-cucumber-html-reporter) | Yes, report folder (CDN optional) | Yes | Yes | No | No | Saved JSON (`saveCollectedJSON`) | Dark mode, custom CSS | ESM (v4) | 22+ | Active | You want a dashboard, multi-run grouping, build-time UI languages (en/es/fr/pt/ar, no German) and a report folder. |
|
|
373
|
+
| [Official Cucumber HTML formatter](https://github.com/cucumber/html-formatter) | Yes, one file | No | Yes | No | No | No | Custom CSS/JS only | ESM | Modern Node | Official Cucumber project | You use Cucumber Messages only and want the official look. |
|
|
374
|
+
| **Tolkira** | **Yes, one file** | **Yes** | **Yes** | **Basic** | **Yes** | **Versioned summary (`--json`)** | **Branding, dark mode; no theme gallery** | **ESM; CJS compat shim** | **22+** | **Active** | **You need one offline file from legacy JSON, Messages, JUnit or Playwright JSON, plus a stable summary for CI and agents.** |
|
|
375
|
+
|
|
127
376
|
The visual comparison uses the report setup from
|
|
128
377
|
[Seed-Test](https://github.com/adessoSE/Seed-Test). If you are curious about
|
|
129
378
|
Seed-Test, you are welcome to take a look; the comparison notes and screenshots
|
|
@@ -131,13 +380,36 @@ are in [`docs/COMPARISON.md`](https://github.com/Silasoa/tolkira/blob/main/docs/
|
|
|
131
380
|
|
|
132
381
|
## Migrating from cucumber-html-reporter
|
|
133
382
|
|
|
134
|
-
|
|
383
|
+
Install Tolkira next to the old reporter and keep the existing JSON output:
|
|
384
|
+
|
|
385
|
+
```shell
|
|
386
|
+
npm i -D tolkira
|
|
387
|
+
```
|
|
388
|
+
|
|
389
|
+
Node.js 22 or newer is required. Node 20 is end-of-life and unsupported;
|
|
390
|
+
upgrading to Node 22+ is the migration cost for both the ESM and CommonJS
|
|
391
|
+
paths. The core and CLI are ESM-only; the compatibility subpath also loads
|
|
392
|
+
from CommonJS through an async wrapper.
|
|
393
|
+
|
|
394
|
+
**Before — CommonJS with cucumber-html-reporter:**
|
|
135
395
|
|
|
136
396
|
```js
|
|
137
|
-
//
|
|
397
|
+
// report.js
|
|
138
398
|
const reporter = require('cucumber-html-reporter');
|
|
139
399
|
|
|
140
|
-
|
|
400
|
+
reporter.generate({
|
|
401
|
+
theme: 'bootstrap',
|
|
402
|
+
jsonFile: 'reports/cucumber.json',
|
|
403
|
+
output: 'reports/report.html',
|
|
404
|
+
brandTitle: 'Checkout acceptance',
|
|
405
|
+
metadata: { Browser: 'Chrome', Environment: 'Staging' },
|
|
406
|
+
});
|
|
407
|
+
```
|
|
408
|
+
|
|
409
|
+
**After — ESM with Tolkira:**
|
|
410
|
+
|
|
411
|
+
```js
|
|
412
|
+
// report.mjs
|
|
141
413
|
import { generate } from 'tolkira/compat/cucumber-html-reporter';
|
|
142
414
|
|
|
143
415
|
await generate({
|
|
@@ -148,11 +420,85 @@ await generate({
|
|
|
148
420
|
});
|
|
149
421
|
```
|
|
150
422
|
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
423
|
+
**If the project must stay CommonJS**, require the compatibility subpath and
|
|
424
|
+
await the async wrapper:
|
|
425
|
+
|
|
426
|
+
```js
|
|
427
|
+
// report.cjs
|
|
428
|
+
const { generate } = require('tolkira/compat/cucumber-html-reporter');
|
|
429
|
+
|
|
430
|
+
async function main() {
|
|
431
|
+
await generate({
|
|
432
|
+
jsonFile: 'reports/cucumber.json',
|
|
433
|
+
output: 'reports/report.html',
|
|
434
|
+
});
|
|
435
|
+
}
|
|
436
|
+
|
|
437
|
+
main().catch((error) => {
|
|
438
|
+
console.error(error);
|
|
439
|
+
process.exitCode = 1;
|
|
440
|
+
});
|
|
441
|
+
```
|
|
442
|
+
|
|
443
|
+
The wrapper is only for the compatibility subpath; the core package, CLI and
|
|
444
|
+
other exports remain ESM-only. There is no default export.
|
|
445
|
+
|
|
446
|
+
The options object is mostly compatible, but the call contract is not. Only
|
|
447
|
+
the import style changing is not the whole story:
|
|
448
|
+
|
|
449
|
+
| Behaviour | `cucumber-html-reporter` | Tolkira compat shim |
|
|
450
|
+
| --- | --- | --- |
|
|
451
|
+
| Input | `jsonFile` falls back to `output + '.json'` when omitted | `jsonFile` or `jsonDir` is required; there is no implicit fallback |
|
|
452
|
+
| Return value | Sync `true` on success without a callback, `undefined` with one; `undefined` for a bad report | Always a `Promise<CompatResult>` with `output`, `warnings` and `summary`; await every call |
|
|
453
|
+
| Errors | The callback receives a string; without a callback a failure can be silent | The promise rejects with an `Error`, and the callback receives the same `Error` |
|
|
454
|
+
| Callback | `callback()` on success, `callback(string)` on failure | `callback(error?)`; the promise still rejects |
|
|
455
|
+
| `jsonDir` | Recursively merges features by `uri`, dedupes them and writes an `output + '.json'` sidecar | Scans recursively; the `jsonDir`-only run writes the merged sidecar (merge by `uri`, previous sidecar excluded on the next run); the report inputs remain separate files |
|
|
456
|
+
| Output timing | The HTML is written synchronously before `generate` returns | The HTML is complete only when the promise resolves |
|
|
457
|
+
| Export | `require('cucumber-html-reporter').generate` | Named `generate`; no default export |
|
|
458
|
+
|
|
459
|
+
**Callback caveat:** callback-only code can ignore the returned promise.
|
|
460
|
+
Tolkira marks that ignored promise handled so it does not crash the process;
|
|
461
|
+
awaiting the same call still throws. Errors are `Error` objects, not the
|
|
462
|
+
legacy strings. If the callback itself throws, handle that error yourself.
|
|
463
|
+
|
|
464
|
+
`theme` is ignored with a warning. Themes, charts, external screenshots and
|
|
465
|
+
browser launch are not reproduced. The shim consumes the same input JSON,
|
|
466
|
+
never the old rendered HTML.
|
|
467
|
+
See [`docs/COMPATIBILITY.md`](https://github.com/Silasoa/tolkira/blob/main/docs/COMPATIBILITY.md)
|
|
468
|
+
for the full mapping and caveats.
|
|
469
|
+
|
|
470
|
+
### From multiple-cucumber-html-reporter
|
|
471
|
+
|
|
472
|
+
There is no MCHR shim; use the core CLI. The common mapping:
|
|
473
|
+
|
|
474
|
+
```shell
|
|
475
|
+
# MCHR config: jsonDir + reportPath + reportName
|
|
476
|
+
mchr
|
|
477
|
+
|
|
478
|
+
# Tolkira
|
|
479
|
+
npx tolkira path/to/jsonDir --out reports/index.html --title "My report"
|
|
480
|
+
```
|
|
481
|
+
|
|
482
|
+
Map `jsonDir` to the input directory, `reportPath`/`reportName` to `--out`,
|
|
483
|
+
`metadata` to repeated `--meta key=value`, `brandLogo` to `--logo`, and
|
|
484
|
+
`language`/`--language`/`--lang` to `--locale`. MCHR 4.6 chooses one UI language
|
|
485
|
+
at build time from en, es, fr, pt and ar (including RTL Arabic; German is not in
|
|
486
|
+
that set); Tolkira supports en and de per report. Neither has an in-report
|
|
487
|
+
switcher; Tolkira's one file carries one locale, while MCHR writes its report
|
|
488
|
+
folder. MCHR localizes its default report titles; Tolkira keeps `Tolkira report`
|
|
489
|
+
unless `--title` overrides it. An unknown MCHR language warns and falls back to
|
|
490
|
+
English on the API/config path, while its `--language`/`--lang` CLI throws.
|
|
491
|
+
Tolkira rejects it too: the CLI exits 2 and the API throws. MCHR's `--email` is a
|
|
492
|
+
boolean that writes `reportPath/email-report.html`; Tolkira's `--email` takes a
|
|
493
|
+
required file path, so a copied bare flag exits 2. MCHR shows per-feature cards
|
|
494
|
+
and the five slowest scenarios; Tolkira shows aggregate counts and the first five
|
|
495
|
+
failed scenarios in summary order, with no per-feature table, metadata or logo.
|
|
496
|
+
Both MCHR and Allure's mail plugin only generate a file and never send, so the
|
|
497
|
+
no-sending boundary is shared. MCHR's dashboard and folder report are not
|
|
498
|
+
reproduced. History is only the opt-in aggregate sidecar described above; there
|
|
499
|
+
is no scenario-level history or multi-run dashboard. See
|
|
500
|
+
[`docs/COMPATIBILITY.md`](https://github.com/Silasoa/tolkira/blob/main/docs/COMPATIBILITY.md#multiple-cucumber-html-reporter)
|
|
501
|
+
for the mapping.
|
|
156
502
|
|
|
157
503
|
## Privacy and limits
|
|
158
504
|
|
|
@@ -161,21 +507,57 @@ caveats.
|
|
|
161
507
|
- Test names, metadata and attachments are treated as untrusted input.
|
|
162
508
|
- Default limits: 100 MB total input, 50 MB per attachment and 100 MB total
|
|
163
509
|
attachments. A warning appears when a report grows beyond 10 MB.
|
|
164
|
-
- JUnit XML is intentionally basic;
|
|
165
|
-
Playwright
|
|
510
|
+
- JUnit XML is intentionally basic; use the native Playwright JSON adapter for
|
|
511
|
+
Playwright projects that can write the JSON reporter.
|
|
512
|
+
- History is opt-in and aggregate-only. `--history <file>` stores counts, status,
|
|
513
|
+
the resolved title (capped at 200 characters), duration and attachment totals
|
|
514
|
+
for the last 30 runs; the report embeds those prior-run aggregates. The CLI is
|
|
515
|
+
the only automatic writer, so use one sidecar per suite and variant and one
|
|
516
|
+
generation at a time. No scenario names, steps, paths, tags or attachment
|
|
517
|
+
content are stored.
|
|
518
|
+
- The opt-in email summary contains feature and scenario names, statuses, counts,
|
|
519
|
+
durations, the title (which may carry a branch or build name) and the report
|
|
520
|
+
basename. It is written only with `--email`; there is no redaction mode, no
|
|
521
|
+
network request and no sending.
|
|
522
|
+
- PDF export is opt-in and Chromium-only. It needs the optional `playwright-core`
|
|
523
|
+
peer and the Chromium headless shell (about 13 MB of package, 286 MB unpacked
|
|
524
|
+
shell and 4 MB of helpers; roughly 303 MB unpacked, download smaller; the full
|
|
525
|
+
Chromium build is not required) in the project where Tolkira runs. It prints A4
|
|
526
|
+
portrait with no header/footer or page numbers and has no CLI filter state,
|
|
527
|
+
Letter/custom paper, landscape or PDF-only logo/Trends. The default Chromium
|
|
528
|
+
launch is not OS-sandboxed; the report CSP and escaped attachments are the
|
|
529
|
+
boundary, so run untrusted attachments in a container or VM. The PDF is not
|
|
530
|
+
byte-identical across engine or font updates.
|
|
166
531
|
- One report is one file. External attachments for very large media are a
|
|
167
532
|
future option.
|
|
168
533
|
|
|
534
|
+
See [`docs/LIMITATIONS.md`](https://github.com/Silasoa/tolkira/blob/main/docs/LIMITATIONS.md)
|
|
535
|
+
for the dated limitations table (last verified 2026-11-20).
|
|
536
|
+
|
|
169
537
|
## Documentation
|
|
170
538
|
|
|
539
|
+
- [`docs/README.md`](https://github.com/Silasoa/tolkira/blob/main/docs/README.md) — map of all project documentation.
|
|
540
|
+
- [`llms.txt`](https://github.com/Silasoa/tolkira/blob/main/llms.txt) — short entry point for AI agents.
|
|
171
541
|
- [`docs/AGENT-INTERFACE.md`](https://github.com/Silasoa/tolkira/blob/main/docs/AGENT-INTERFACE.md) — JSON schema, CLI
|
|
172
542
|
contract and exit codes.
|
|
543
|
+
- [`docs/CI.md`](https://github.com/Silasoa/tolkira/blob/main/docs/CI.md) — GitHub annotations, GitLab and step-summary
|
|
544
|
+
output.
|
|
545
|
+
- [`docs/EMAIL.md`](https://github.com/Silasoa/tolkira/blob/main/docs/EMAIL.md) — opt-in HTML email summary, CLI/API and
|
|
546
|
+
CI mail-step example.
|
|
547
|
+
- [`docs/PDF.md`](https://github.com/Silasoa/tolkira/blob/main/docs/PDF.md) — opt-in PDF export, engine install, CLI/API,
|
|
548
|
+
write order and limits.
|
|
549
|
+
- [`docs/LIMITATIONS.md`](https://github.com/Silasoa/tolkira/blob/main/docs/LIMITATIONS.md) — dated limitations table
|
|
550
|
+
(last verified 2026-11-20).
|
|
173
551
|
- [`docs/CUCUMBER-COMPATIBILITY.md`](https://github.com/Silasoa/tolkira/blob/main/docs/CUCUMBER-COMPATIBILITY.md) — tested
|
|
174
552
|
Cucumber producers and versions.
|
|
175
553
|
- [`docs/JUNIT-XML.md`](https://github.com/Silasoa/tolkira/blob/main/docs/JUNIT-XML.md) — JUnit basic-mode mapping and
|
|
176
554
|
limits.
|
|
555
|
+
- [`docs/PLAYWRIGHT-JSON.md`](https://github.com/Silasoa/tolkira/blob/main/docs/PLAYWRIGHT-JSON.md) — native Playwright
|
|
556
|
+
JSON mapping and limits.
|
|
177
557
|
- [`docs/COMPATIBILITY.md`](https://github.com/Silasoa/tolkira/blob/main/docs/COMPATIBILITY.md) — migration from
|
|
178
558
|
cucumber-html-reporter.
|
|
559
|
+
- [`docs/I18N.md`](https://github.com/Silasoa/tolkira/blob/main/docs/I18N.md) — report locales, catalog rules,
|
|
560
|
+
formatting and the German glossary.
|
|
179
561
|
- [`docs/COMPARISON.md`](https://github.com/Silasoa/tolkira/blob/main/docs/COMPARISON.md) — Seed-Test comparison and
|
|
180
562
|
remaining parity gaps.
|
|
181
563
|
|
|
@@ -189,12 +571,14 @@ npx playwright install chromium firefox webkit
|
|
|
189
571
|
npm run check
|
|
190
572
|
npm run test:e2e
|
|
191
573
|
npm run stress -- 1000
|
|
574
|
+
npm run bench:ansi
|
|
192
575
|
```
|
|
193
576
|
|
|
194
577
|
`npm run check` runs typecheck, lint, unit tests, build and the CSS generation
|
|
195
578
|
step. `npm run test:e2e` runs the browser tests in Chromium, Firefox and
|
|
196
579
|
WebKit. `npm run stress -- 1000` builds a 1,000-scenario report and reports size
|
|
197
|
-
and timing.
|
|
580
|
+
and timing. `npm run bench:ansi` measures `stripAnsi` on fixed message corpora
|
|
581
|
+
and enforces the 500 ms production budget.
|
|
198
582
|
|
|
199
583
|
Build once and run the CLI from `dist`:
|
|
200
584
|
|
package/SECURITY.md
CHANGED
|
@@ -26,5 +26,8 @@ Tolkira processes untrusted test output. Security-relevant areas include:
|
|
|
26
26
|
- denial of service through very large reports or attachments;
|
|
27
27
|
- dependency vulnerabilities.
|
|
28
28
|
|
|
29
|
+
HTML attachments are always escaped text, and SVG attachments are only used as
|
|
30
|
+
`<img>` data-URI sources; neither is injected as markup or a document.
|
|
31
|
+
|
|
29
32
|
Tolkira does not send telemetry and does not make network requests. A report
|
|
30
33
|
should remain fully offline.
|
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
import type { Attachment } from '@cucumber/messages';
|
|
2
|
+
/** Per-attachment cap; the sanitizer checks decoded bytes, the Playwright adapter checks file size. */
|
|
3
|
+
export declare const MAX_ATTACHMENT_BYTES: number;
|
|
4
|
+
/** Total attachment cap; the sanitizer applies it per report, the Playwright adapter per input. */
|
|
5
|
+
export declare const MAX_TOTAL_ATTACHMENT_BYTES: number;
|
|
6
|
+
/** Text attachments above this size skip JSON pretty-printing and ANSI colouring. */
|
|
7
|
+
export declare const MAX_TEXT_ATTACHMENT_BYTES = 262144;
|
|
8
|
+
export type AttachmentKind = 'image' | 'video' | 'audio' | 'text' | 'binary';
|
|
9
|
+
export type AttachmentTextFormat = 'json' | 'uri-list' | 'log' | 'plain';
|
|
10
|
+
export interface AttachmentMetadata {
|
|
11
|
+
/** Allowlisted media type. */
|
|
12
|
+
mediaType: string;
|
|
13
|
+
kind: AttachmentKind;
|
|
14
|
+
/** Non-empty Cucumber file name; otherwise the deterministic fallback. */
|
|
15
|
+
fileName: string;
|
|
16
|
+
/** Decoded bytes, not the base64 length. */
|
|
17
|
+
bytes: number;
|
|
18
|
+
/** Text presentation the renderer uses. */
|
|
19
|
+
textFormat: AttachmentTextFormat;
|
|
20
|
+
}
|
|
21
|
+
export declare function normalizedMediaType(mediaType: string): string;
|
|
22
|
+
/**
|
|
23
|
+
* Normalises a declared media type and drops everything outside the report's
|
|
24
|
+
* renderer list. Unknown or forged types (XHTML, XML, comma-joined values)
|
|
25
|
+
* become application/octet-stream so they can never reach a data URI verbatim.
|
|
26
|
+
*/
|
|
27
|
+
export declare function safeMediaType(mediaType: string): string;
|
|
28
|
+
/**
|
|
29
|
+
* Counts canonical base64 decoded bytes without decoding; non-canonical bodies
|
|
30
|
+
* keep the length-based estimate. This is the summary's `attachments.bytes`.
|
|
31
|
+
*/
|
|
32
|
+
export declare function attachmentBytes(attachment: Pick<Attachment, 'body' | 'contentEncoding'>): number;
|
|
33
|
+
export declare function attachmentMetadata(attachment: Pick<Attachment, 'body' | 'contentEncoding' | 'fileName' | 'mediaType'>): AttachmentMetadata;
|
package/dist/ci.d.ts
ADDED
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
import type { ReportSummary } from './summary.js';
|
|
2
|
+
export type CiFormat = 'github' | 'markdown';
|
|
3
|
+
export interface CiFormatOptions {
|
|
4
|
+
/** Markdown heading; defaults to "Tolkira report". */
|
|
5
|
+
title?: string;
|
|
6
|
+
}
|
|
7
|
+
/** Formats the summary as GitHub Actions workflow commands. */
|
|
8
|
+
export declare function formatGitHubAnnotations(summary: ReportSummary): string;
|
|
9
|
+
/** Formats the summary as deterministic, inert Markdown. */
|
|
10
|
+
export declare function formatMarkdownSummary(summary: ReportSummary, options?: CiFormatOptions): string;
|
|
11
|
+
/** Dispatches between the two CI formats. */
|
|
12
|
+
export declare function formatCiOutput(summary: ReportSummary, format: CiFormat, options?: CiFormatOptions): string;
|