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.
Files changed (64) hide show
  1. package/DESIGN.md +131 -9
  2. package/GLOSSARY.md +201 -1
  3. package/README.md +413 -29
  4. package/SECURITY.md +3 -0
  5. package/dist/attachment.d.ts +33 -0
  6. package/dist/attempt-diagnostics.d.ts +2 -0
  7. package/dist/ci.d.ts +12 -0
  8. package/dist/cli.js +6881 -2691
  9. package/dist/cli.js.map +4 -4
  10. package/dist/compat/cucumber-html-reporter.cjs +12 -0
  11. package/dist/compat/cucumber-html-reporter.d.cts +10 -0
  12. package/dist/compat/cucumber-html-reporter.js +263 -26
  13. package/dist/compat/cucumber-html-reporter.js.map +4 -4
  14. package/dist/compat/options.d.ts +4 -0
  15. package/dist/email.d.ts +18 -0
  16. package/dist/history.d.ts +41 -0
  17. package/dist/i18n/catalogs.d.ts +7 -0
  18. package/dist/index.d.ts +15 -7
  19. package/dist/index.js +5301 -1709
  20. package/dist/index.js.map +4 -4
  21. package/dist/input/background.d.ts +4 -0
  22. package/dist/input/detect.d.ts +30 -0
  23. package/dist/input/load.d.ts +3 -0
  24. package/dist/input/playwright.d.ts +14 -0
  25. package/dist/options.d.ts +18 -0
  26. package/dist/output.d.ts +9 -1
  27. package/dist/pdf.d.ts +9 -0
  28. package/dist/render/ansi.d.ts +2 -0
  29. package/dist/render/attachments.d.ts +3 -0
  30. package/dist/render/ci.d.ts +4 -0
  31. package/dist/render/client-bundle.d.ts +1 -0
  32. package/dist/render/client-i18n.d.ts +7 -0
  33. package/dist/render/details.d.ts +5 -0
  34. package/dist/render/dom-contract.d.ts +42 -0
  35. package/dist/render/format.d.ts +34 -0
  36. package/dist/render/html.d.ts +2 -9
  37. package/dist/render/i18n.d.ts +30 -0
  38. package/dist/render/markdown.d.ts +2 -0
  39. package/dist/render/matrix.d.ts +3 -0
  40. package/dist/render/print-script.d.ts +1 -0
  41. package/dist/render/report-client.d.ts +1 -0
  42. package/dist/render/report.d.ts +4 -0
  43. package/dist/render/search.d.ts +21 -0
  44. package/dist/render/trends.d.ts +7 -0
  45. package/dist/render/triage.d.ts +5 -0
  46. package/dist/render/types.d.ts +26 -0
  47. package/dist/report/index-run.d.ts +69 -0
  48. package/dist/report/model.d.ts +96 -6
  49. package/dist/report/status.d.ts +12 -0
  50. package/dist/stream.d.ts +15 -0
  51. package/dist/summary.d.ts +17 -2
  52. package/dist/text.d.ts +15 -0
  53. package/dist/warnings.d.ts +6 -0
  54. package/docs/AGENT-INTERFACE.md +504 -33
  55. package/docs/CI.md +185 -0
  56. package/docs/COMPATIBILITY.md +121 -16
  57. package/docs/CUCUMBER-COMPATIBILITY.md +232 -15
  58. package/docs/EMAIL.md +273 -0
  59. package/docs/I18N.md +241 -0
  60. package/docs/JUNIT-XML.md +46 -4
  61. package/docs/LIMITATIONS.md +21 -0
  62. package/docs/PDF.md +255 -0
  63. package/llms.txt +63 -0
  64. 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 and JUnit XML in one self-contained HTML file.**
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
- stay inside the file. There is no server, no CDN and no telemetry.
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.2.0** · [npm](https://www.npmjs.com/package/tolkira) · [Changelog](https://github.com/Silasoa/tolkira/blob/main/docs/CHANGELOG.md)
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 run it without a global install:
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
- For CI tools and AI agents, ask for the stable JSON summary instead of scraping
56
- the HTML:
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
- tolkira test-results/ --out report.html --json
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. On phones the strip is hidden and the feature row keeps the
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 legacy JSON adapter.
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; open matching features automatically and highlight matches.
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 Cucumber environment (producer, runtime, OS, CPU,
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 tested with real output. Other producers often work; the adapter follows the Cucumber legacy dialect. |
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 and
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 **and** modern Messages;
343
+ - legacy JSON, modern Messages and native Playwright JSON;
117
344
  - JUnit XML as cheap breadth for non-Cucumber teams;
118
- - screenshots and attachments that stay in the report;
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
- The old options object is accepted as-is; only the import changes.
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
- // before
397
+ // report.js
138
398
  const reporter = require('cucumber-html-reporter');
139
399
 
140
- // after
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
- The shim is experimental. Themes, charts, external screenshots and browser
152
- launch are not reproduced; they warn and use Tolkira's defaults. It consumes
153
- the same input JSON, never the old rendered HTML. See
154
- [`docs/COMPATIBILITY.md`](https://github.com/Silasoa/tolkira/blob/main/docs/COMPATIBILITY.md) for the full mapping and
155
- caveats.
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; it is not a replacement for a native
165
- Playwright, Jest or Allure report.
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;
@@ -0,0 +1,2 @@
1
+ export declare function recordSkippedAttachments(started: object, count: number): void;
2
+ export declare function skippedAttachmentsOf(started: object): number | undefined;
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;