tolkira 0.3.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 +115 -8
- package/README.md +229 -37
- 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 +7099 -3785
- package/dist/cli.js.map +4 -4
- package/dist/compat/cucumber-html-reporter.js +174 -8
- package/dist/compat/cucumber-html-reporter.js.map +4 -4
- package/dist/compat/options.d.ts +2 -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 +12 -1
- package/dist/index.js +5148 -2453
- package/dist/index.js.map +4 -4
- package/dist/input/detect.d.ts +30 -0
- package/dist/input/load.d.ts +1 -0
- package/dist/input/playwright.d.ts +14 -0
- package/dist/options.d.ts +6 -0
- package/dist/output.d.ts +7 -1
- package/dist/pdf.d.ts +9 -0
- package/dist/render/attachments.d.ts +3 -0
- package/dist/render/ci.d.ts +4 -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 -1
- 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 +3 -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 +11 -2
- package/dist/summary.d.ts +3 -0
- package/dist/warnings.d.ts +6 -0
- package/docs/AGENT-INTERFACE.md +367 -33
- package/docs/CI.md +185 -0
- package/docs/COMPATIBILITY.md +72 -11
- package/docs/CUCUMBER-COMPATIBILITY.md +50 -26
- package/docs/EMAIL.md +273 -0
- package/docs/I18N.md +241 -0
- package/docs/JUNIT-XML.md +19 -2
- package/docs/LIMITATIONS.md +10 -6
- package/docs/PDF.md +255 -0
- package/llms.txt +36 -4
- package/package.json +21 -5
- package/dist/report/attachment.d.ts +0 -10
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,
|
|
@@ -53,18 +55,99 @@ tolkira test-results/ --out report.html \
|
|
|
53
55
|
|
|
54
56
|
# Embed a logo (PNG, JPEG, GIF, WebP or SVG)
|
|
55
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
|
|
56
70
|
```
|
|
57
71
|
|
|
58
72
|
Tolkira accepts one or more files and directories. A directory is scanned
|
|
59
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
|
+
```
|
|
128
|
+
|
|
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.
|
|
60
142
|
|
|
61
143
|
## For agents and CI
|
|
62
144
|
|
|
63
|
-
Install as a project dependency and write
|
|
145
|
+
Install as a project dependency and write the report, the optional email body
|
|
146
|
+
and the JSON summary:
|
|
64
147
|
|
|
65
148
|
```shell
|
|
66
149
|
npm install --save-dev tolkira
|
|
67
|
-
npx tolkira test-results/ --out report.html --title "CI run" --json > summary.json
|
|
150
|
+
npx tolkira test-results/ --out report.html --email email.html --title "CI run" --json > summary.json
|
|
68
151
|
```
|
|
69
152
|
|
|
70
153
|
GitHub Actions step:
|
|
@@ -72,18 +155,37 @@ GitHub Actions step:
|
|
|
72
155
|
```yaml
|
|
73
156
|
- name: Generate Cucumber report
|
|
74
157
|
if: always()
|
|
75
|
-
run: npx tolkira test-results/ --out report.html --title "CI run" --json > summary.json
|
|
158
|
+
run: npx tolkira test-results/ --out report.html --email email.html --history .history/history.json --title "CI run" --json > summary.json
|
|
76
159
|
|
|
77
160
|
- name: Upload report
|
|
78
161
|
if: always()
|
|
79
162
|
uses: actions/upload-artifact@v4
|
|
80
163
|
with:
|
|
81
164
|
name: cucumber-report
|
|
165
|
+
include-hidden-files: true
|
|
82
166
|
path: |
|
|
83
167
|
report.html
|
|
168
|
+
email.html
|
|
84
169
|
summary.json
|
|
170
|
+
.history/history.json
|
|
85
171
|
```
|
|
86
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
|
+
|
|
87
189
|
`--json` writes exactly one JSON document to stdout; warnings go to stderr.
|
|
88
190
|
Exit code 0 means the report was generated, not that the tests passed. Read
|
|
89
191
|
`status` and `counts` from the summary. Abridged real output (counts and steps
|
|
@@ -128,6 +230,32 @@ outcome. Upload report.html as the human-facing artifact.
|
|
|
128
230
|
See [`docs/AGENT-INTERFACE.md`](https://github.com/Silasoa/tolkira/blob/main/docs/AGENT-INTERFACE.md)
|
|
129
231
|
for the full schema and exit codes.
|
|
130
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
|
+
|
|
131
259
|
## What you get
|
|
132
260
|
|
|
133
261
|
- **One file that works offline.** CSS, JavaScript and attachments are inline.
|
|
@@ -137,20 +265,24 @@ for the full schema and exit codes.
|
|
|
137
265
|
with links that open the scenario detail.
|
|
138
266
|
- **Multi-file context.** A source strip shows per-input status, counts and a
|
|
139
267
|
proportion bar when the run has more than one input file and provenance is
|
|
140
|
-
unambiguous.
|
|
141
|
-
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.
|
|
142
270
|
- **Screenshots and attachments that survive.** Images, text, video, audio and
|
|
143
|
-
files are preserved through the
|
|
271
|
+
files are preserved through the input adapters where available; skipped path
|
|
272
|
+
attachments are named in the report.
|
|
144
273
|
- **Search and filters.** Search scenarios, features, steps and tags; filter by
|
|
145
|
-
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.
|
|
146
276
|
- **Rendered descriptions.** Feature, rule, background, scenario and examples
|
|
147
277
|
descriptions render a safe GFM subset - headings, emphasis, code, lists,
|
|
148
|
-
tables, quotes and http(s)/mailto links - from Messages, legacy JSON
|
|
278
|
+
tables, quotes and http(s)/mailto links - from Messages, legacy JSON, JUnit
|
|
279
|
+
and Playwright JSON.
|
|
149
280
|
- **Tag expressions.** Search accepts the official Cucumber grammar
|
|
150
281
|
(`@a and not @b`, parentheses, escaped tags). Mixed text and tags fall back to
|
|
151
282
|
plain substring search.
|
|
152
|
-
- **Shareable filtered views.** Search, hidden statuses
|
|
153
|
-
|
|
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.
|
|
154
286
|
- **Parameter highlighting.** Matched step arguments render with their Cucumber
|
|
155
287
|
parameter type from Messages; ambiguous or unmatched steps stay plain.
|
|
156
288
|
- **Messages stream adapter.** `CucumberHtmlStream` is shape-compatible with the
|
|
@@ -159,14 +291,26 @@ for the full schema and exit codes.
|
|
|
159
291
|
- **Copy failure.** Copy a failed scenario's feature, failed step and error as
|
|
160
292
|
plain text for a ticket or an agent.
|
|
161
293
|
- **A Details view when you need it.** Status distribution, a feature-by-status
|
|
162
|
-
matrix, run metadata and the
|
|
294
|
+
matrix, run metadata and the Run environment (producer, runtime, OS, CPU,
|
|
163
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.
|
|
164
301
|
- **A stable summary for agents.** `--json` and `summarizeReport()` return a
|
|
165
302
|
versioned schema with counts, durations, scenarios, steps and failure
|
|
166
303
|
messages.
|
|
167
304
|
- **Accessible by default.** Keyboard navigation, visible focus, text status
|
|
168
305
|
labels as well as colour, dark mode and 200% zoom reflow. Accessibility is an
|
|
169
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).
|
|
170
314
|
- **Your branding.** Title, metadata, logo and accent colour without forking the
|
|
171
315
|
shell.
|
|
172
316
|
|
|
@@ -174,14 +318,16 @@ for the full schema and exit codes.
|
|
|
174
318
|
|
|
175
319
|
| Input | What works |
|
|
176
320
|
| --- | --- |
|
|
177
|
-
| **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
|
|
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. |
|
|
178
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. |
|
|
179
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. |
|
|
180
325
|
|
|
181
326
|
Multiple files and mixed formats can be merged into one run. See
|
|
182
327
|
[`docs/CUCUMBER-COMPATIBILITY.md`](https://github.com/Silasoa/tolkira/blob/main/docs/CUCUMBER-COMPATIBILITY.md) for the
|
|
183
|
-
tested producer matrix
|
|
184
|
-
[`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.
|
|
185
331
|
|
|
186
332
|
## Why Tolkira exists
|
|
187
333
|
|
|
@@ -194,9 +340,9 @@ work offline lose their layout and charts.
|
|
|
194
340
|
Tolkira keeps the old input working and fixes the parts that hurt:
|
|
195
341
|
|
|
196
342
|
- one offline file instead of CDN dependencies;
|
|
197
|
-
- legacy JSON
|
|
343
|
+
- legacy JSON, modern Messages and native Playwright JSON;
|
|
198
344
|
- JUnit XML as cheap breadth for non-Cucumber teams;
|
|
199
|
-
- screenshots and attachments
|
|
345
|
+
- screenshots and attachments embedded where available;
|
|
200
346
|
- a stable JSON summary for agents and CI;
|
|
201
347
|
- a small, reviewed dependency surface.
|
|
202
348
|
|
|
@@ -209,22 +355,23 @@ CDN or telemetry.
|
|
|
209
355
|
|
|
210
356
|
"Parity" in this project means content and navigation: the same statements,
|
|
211
357
|
steps, tags, statuses, durations and descriptions, plus search, tag expressions
|
|
212
|
-
and shareable filter URLs, whether the input is legacy JSON, Messages or
|
|
358
|
+
and shareable filter URLs, whether the input is legacy JSON, Messages, JUnit or
|
|
359
|
+
Playwright JSON.
|
|
213
360
|
It does not mean theme parity with `cucumber-html-reporter`, a report folder, or
|
|
214
361
|
external attachments; Tolkira deliberately stays one offline file. The honest
|
|
215
362
|
claim is credible Messages report parity, not full formatter parity.
|
|
216
363
|
|
|
217
364
|
### How it compares
|
|
218
365
|
|
|
219
|
-
Last checked 2026-11-
|
|
366
|
+
Last checked 2026-11-20 against the current package docs. Trade-offs are
|
|
220
367
|
deliberate; pick the tool that fits the job.
|
|
221
368
|
|
|
222
|
-
| Tool | Offline | Legacy JSON | Messages | JUnit | JSON summary | Themes | ESM/CJS | Node | Maintenance | Choose it if… |
|
|
223
|
-
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
|
|
224
|
-
| [cucumber-html-reporter](https://github.com/gkushang/cucumber-html-reporter) | No, CDN assets | Yes | 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. |
|
|
225
|
-
| [multiple-cucumber-html-reporter](https://github.com/WasiqB/multiple-cucumber-html-reporter) | Yes, report folder (CDN optional) | Yes | Yes | No | Saved JSON (`saveCollectedJSON`) | Dark mode, custom CSS | ESM (v4) | 22+ | Active | You want a dashboard, multi-run grouping,
|
|
226
|
-
| [Official Cucumber HTML formatter](https://github.com/cucumber/html-formatter) | Yes, one file | No | Yes | No | No | Custom CSS/JS only | ESM | Modern Node | Official Cucumber project | You use Cucumber Messages only and want the official look. |
|
|
227
|
-
| **Tolkira** | **Yes, one file** | **Yes** | **Yes** | **Basic** | **Versioned summary (`--json`)** | **Branding, dark mode; no theme gallery** | **ESM; CJS compat shim** | **22+** | **Active** | **You need one offline file from legacy JSON
|
|
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.** |
|
|
228
375
|
|
|
229
376
|
The visual comparison uses the report setup from
|
|
230
377
|
[Seed-Test](https://github.com/adessoSE/Seed-Test). If you are curious about
|
|
@@ -305,7 +452,7 @@ the import style changing is not the whole story:
|
|
|
305
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 |
|
|
306
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` |
|
|
307
454
|
| Callback | `callback()` on success, `callback(string)` on failure | `callback(error?)`; the promise still rejects |
|
|
308
|
-
| `jsonDir` | Recursively merges features by `uri`, dedupes them and writes an `output + '.json'` sidecar | Scans recursively
|
|
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 |
|
|
309
456
|
| Output timing | The HTML is written synchronously before `generate` returns | The HTML is complete only when the promise resolves |
|
|
310
457
|
| Export | `require('cucumber-html-reporter').generate` | Named `generate`; no default export |
|
|
311
458
|
|
|
@@ -333,9 +480,23 @@ npx tolkira path/to/jsonDir --out reports/index.html --title "My report"
|
|
|
333
480
|
```
|
|
334
481
|
|
|
335
482
|
Map `jsonDir` to the input directory, `reportPath`/`reportName` to `--out`,
|
|
336
|
-
`metadata` to repeated `--meta key=value`,
|
|
337
|
-
|
|
338
|
-
|
|
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
|
|
339
500
|
[`docs/COMPATIBILITY.md`](https://github.com/Silasoa/tolkira/blob/main/docs/COMPATIBILITY.md#multiple-cucumber-html-reporter)
|
|
340
501
|
for the mapping.
|
|
341
502
|
|
|
@@ -346,28 +507,57 @@ for the mapping.
|
|
|
346
507
|
- Test names, metadata and attachments are treated as untrusted input.
|
|
347
508
|
- Default limits: 100 MB total input, 50 MB per attachment and 100 MB total
|
|
348
509
|
attachments. A warning appears when a report grows beyond 10 MB.
|
|
349
|
-
- JUnit XML is intentionally basic;
|
|
350
|
-
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.
|
|
351
531
|
- One report is one file. External attachments for very large media are a
|
|
352
532
|
future option.
|
|
353
533
|
|
|
354
534
|
See [`docs/LIMITATIONS.md`](https://github.com/Silasoa/tolkira/blob/main/docs/LIMITATIONS.md)
|
|
355
|
-
for the dated limitations table (last verified 2026-11-
|
|
356
|
-
remaining Behave real-run gap.
|
|
535
|
+
for the dated limitations table (last verified 2026-11-20).
|
|
357
536
|
|
|
358
537
|
## Documentation
|
|
359
538
|
|
|
539
|
+
- [`docs/README.md`](https://github.com/Silasoa/tolkira/blob/main/docs/README.md) — map of all project documentation.
|
|
360
540
|
- [`llms.txt`](https://github.com/Silasoa/tolkira/blob/main/llms.txt) — short entry point for AI agents.
|
|
361
541
|
- [`docs/AGENT-INTERFACE.md`](https://github.com/Silasoa/tolkira/blob/main/docs/AGENT-INTERFACE.md) — JSON schema, CLI
|
|
362
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.
|
|
363
549
|
- [`docs/LIMITATIONS.md`](https://github.com/Silasoa/tolkira/blob/main/docs/LIMITATIONS.md) — dated limitations table
|
|
364
|
-
(last verified 2026-11-
|
|
550
|
+
(last verified 2026-11-20).
|
|
365
551
|
- [`docs/CUCUMBER-COMPATIBILITY.md`](https://github.com/Silasoa/tolkira/blob/main/docs/CUCUMBER-COMPATIBILITY.md) — tested
|
|
366
552
|
Cucumber producers and versions.
|
|
367
553
|
- [`docs/JUNIT-XML.md`](https://github.com/Silasoa/tolkira/blob/main/docs/JUNIT-XML.md) — JUnit basic-mode mapping and
|
|
368
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.
|
|
369
557
|
- [`docs/COMPATIBILITY.md`](https://github.com/Silasoa/tolkira/blob/main/docs/COMPATIBILITY.md) — migration from
|
|
370
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.
|
|
371
561
|
- [`docs/COMPARISON.md`](https://github.com/Silasoa/tolkira/blob/main/docs/COMPARISON.md) — Seed-Test comparison and
|
|
372
562
|
remaining parity gaps.
|
|
373
563
|
|
|
@@ -381,12 +571,14 @@ npx playwright install chromium firefox webkit
|
|
|
381
571
|
npm run check
|
|
382
572
|
npm run test:e2e
|
|
383
573
|
npm run stress -- 1000
|
|
574
|
+
npm run bench:ansi
|
|
384
575
|
```
|
|
385
576
|
|
|
386
577
|
`npm run check` runs typecheck, lint, unit tests, build and the CSS generation
|
|
387
578
|
step. `npm run test:e2e` runs the browser tests in Chromium, Firefox and
|
|
388
579
|
WebKit. `npm run stress -- 1000` builds a 1,000-scenario report and reports size
|
|
389
|
-
and timing.
|
|
580
|
+
and timing. `npm run bench:ansi` measures `stripAnsi` on fixed message corpora
|
|
581
|
+
and enforces the 500 ms production budget.
|
|
390
582
|
|
|
391
583
|
Build once and run the CLI from `dist`:
|
|
392
584
|
|
|
@@ -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;
|