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.
Files changed (56) hide show
  1. package/DESIGN.md +131 -9
  2. package/GLOSSARY.md +115 -8
  3. package/README.md +229 -37
  4. package/dist/attachment.d.ts +33 -0
  5. package/dist/attempt-diagnostics.d.ts +2 -0
  6. package/dist/ci.d.ts +12 -0
  7. package/dist/cli.js +7099 -3785
  8. package/dist/cli.js.map +4 -4
  9. package/dist/compat/cucumber-html-reporter.js +174 -8
  10. package/dist/compat/cucumber-html-reporter.js.map +4 -4
  11. package/dist/compat/options.d.ts +2 -0
  12. package/dist/email.d.ts +18 -0
  13. package/dist/history.d.ts +41 -0
  14. package/dist/i18n/catalogs.d.ts +7 -0
  15. package/dist/index.d.ts +12 -1
  16. package/dist/index.js +5148 -2453
  17. package/dist/index.js.map +4 -4
  18. package/dist/input/detect.d.ts +30 -0
  19. package/dist/input/load.d.ts +1 -0
  20. package/dist/input/playwright.d.ts +14 -0
  21. package/dist/options.d.ts +6 -0
  22. package/dist/output.d.ts +7 -1
  23. package/dist/pdf.d.ts +9 -0
  24. package/dist/render/attachments.d.ts +3 -0
  25. package/dist/render/ci.d.ts +4 -0
  26. package/dist/render/client-i18n.d.ts +7 -0
  27. package/dist/render/details.d.ts +5 -0
  28. package/dist/render/dom-contract.d.ts +42 -0
  29. package/dist/render/format.d.ts +34 -0
  30. package/dist/render/html.d.ts +2 -9
  31. package/dist/render/i18n.d.ts +30 -0
  32. package/dist/render/markdown.d.ts +2 -1
  33. package/dist/render/matrix.d.ts +3 -0
  34. package/dist/render/print-script.d.ts +1 -0
  35. package/dist/render/report-client.d.ts +1 -0
  36. package/dist/render/report.d.ts +4 -0
  37. package/dist/render/search.d.ts +3 -0
  38. package/dist/render/trends.d.ts +7 -0
  39. package/dist/render/triage.d.ts +5 -0
  40. package/dist/render/types.d.ts +26 -0
  41. package/dist/report/index-run.d.ts +69 -0
  42. package/dist/report/model.d.ts +11 -2
  43. package/dist/summary.d.ts +3 -0
  44. package/dist/warnings.d.ts +6 -0
  45. package/docs/AGENT-INTERFACE.md +367 -33
  46. package/docs/CI.md +185 -0
  47. package/docs/COMPATIBILITY.md +72 -11
  48. package/docs/CUCUMBER-COMPATIBILITY.md +50 -26
  49. package/docs/EMAIL.md +273 -0
  50. package/docs/I18N.md +241 -0
  51. package/docs/JUNIT-XML.md +19 -2
  52. package/docs/LIMITATIONS.md +10 -6
  53. package/docs/PDF.md +255 -0
  54. package/llms.txt +36 -4
  55. package/package.json +21 -5
  56. 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 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.3.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,
@@ -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 both artifacts:
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. On phones the strip is hidden and the feature row keeps the
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 legacy JSON adapter.
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; 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.
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 and JUnit.
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 and the tag filter live
153
- in `?query=`, repeated `?hide=` and `?tag=`, so a URL reproduces the same view.
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 Cucumber environment (producer, runtime, OS, CPU,
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 does not yet include attachments or doc strings; 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. |
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 and
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 **and** modern Messages;
343
+ - legacy JSON, modern Messages and native Playwright JSON;
198
344
  - JUnit XML as cheap breadth for non-Cucumber teams;
199
- - screenshots and attachments that stay in the report;
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 JUnit.
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-11 against the current package docs. Trade-offs are
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, i18n and a report folder. |
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 and/or Messages, plus a stable summary for CI and agents.** |
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 but passes the files as separate inputs; writes no sidecar and does not dedupe |
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`, and `brandLogo` to `--logo`.
337
- Dashboard, history, trends, i18n, email reports and the multi-file folder report
338
- are not reproduced. See
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; it is not a replacement for a native
350
- 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.
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-11), including the
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-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;
@@ -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;