tolkira 0.2.0 → 0.3.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/GLOSSARY.md +93 -0
- package/README.md +207 -15
- package/SECURITY.md +3 -0
- package/dist/cli.js +1455 -579
- package/dist/cli.js.map +4 -4
- package/dist/compat/cucumber-html-reporter.cjs +12 -0
- package/dist/compat/cucumber-html-reporter.d.cts +10 -0
- package/dist/compat/cucumber-html-reporter.js +95 -24
- package/dist/compat/cucumber-html-reporter.js.map +4 -4
- package/dist/compat/options.d.ts +2 -0
- package/dist/index.d.ts +4 -7
- package/dist/index.js +1449 -552
- package/dist/index.js.map +4 -4
- package/dist/input/background.d.ts +4 -0
- package/dist/input/load.d.ts +2 -0
- package/dist/options.d.ts +12 -0
- package/dist/output.d.ts +2 -0
- package/dist/render/ansi.d.ts +2 -0
- package/dist/render/client-bundle.d.ts +1 -0
- package/dist/render/markdown.d.ts +1 -0
- package/dist/render/search.d.ts +18 -0
- package/dist/report/attachment.d.ts +10 -0
- package/dist/report/model.d.ts +85 -4
- package/dist/report/status.d.ts +12 -0
- package/dist/stream.d.ts +15 -0
- package/dist/summary.d.ts +14 -2
- package/dist/text.d.ts +15 -0
- package/docs/AGENT-INTERFACE.md +158 -21
- package/docs/COMPATIBILITY.md +51 -7
- package/docs/CUCUMBER-COMPATIBILITY.md +193 -0
- package/docs/JUNIT-XML.md +27 -2
- package/docs/LIMITATIONS.md +17 -0
- package/llms.txt +31 -0
- package/package.json +30 -8
package/GLOSSARY.md
CHANGED
|
@@ -15,10 +15,31 @@ used by official Cucumber implementations.
|
|
|
15
15
|
**Attachment** — a binary or text artefact attached to a test step, scenario or
|
|
16
16
|
hook. Screenshots are attachments.
|
|
17
17
|
|
|
18
|
+
**Attachment fallback name** — the deterministic `attachment.<ext>` name used
|
|
19
|
+
when an attachment has no Cucumber `fileName`. Known parameterised media types
|
|
20
|
+
keep their extension; unknown types normalise to `application/octet-stream` and
|
|
21
|
+
`attachment.bin`.
|
|
22
|
+
|
|
23
|
+
**CI metadata** — the optional Messages `meta.ci` block: CI name and URL plus
|
|
24
|
+
git remote, revision, branch and tag. It renders in the HTML header and Details
|
|
25
|
+
and never in the JSON summary.
|
|
26
|
+
|
|
27
|
+
**ANSI log** — a `text/x.cucumber.log+plain` attachment. Tolkira renders its SGR
|
|
28
|
+
colours, including 256-colour and truecolour, strips other control sequences and
|
|
29
|
+
offers a copy action.
|
|
30
|
+
|
|
18
31
|
**Embedding** — the legacy JSON representation of an attachment (`embeddings[]`).
|
|
19
32
|
|
|
20
33
|
**Adapter** — code that turns an input format into Cucumber Messages.
|
|
21
34
|
|
|
35
|
+
**Stream adapter** — `CucumberHtmlStream`, a shape-compatible Node `Transform`
|
|
36
|
+
that accepts Messages envelopes and renders one HTML document on flush with
|
|
37
|
+
`RenderReportOptions`. It buffers the run; it is not an incremental renderer.
|
|
38
|
+
|
|
39
|
+
**Parameter highlighting** — wrapping the fragments matched by a single
|
|
40
|
+
`stepMatchArgumentsLists` entry in `span.param`, labelled with the Cucumber
|
|
41
|
+
parameter type. It is cosmetic and does not change step text or the summary.
|
|
42
|
+
|
|
22
43
|
**Normalisation** — converting legacy JSON into Messages so one renderer can
|
|
23
44
|
handle both.
|
|
24
45
|
|
|
@@ -40,6 +61,78 @@ proportion bar.
|
|
|
40
61
|
**Feature matrix** — the Details table with one row per feature and one count
|
|
41
62
|
column per status present in the run, plus total and duration.
|
|
42
63
|
|
|
64
|
+
**Scenario outline** — a Gherkin scenario template with an Examples table.
|
|
65
|
+
Tolkira renders one outline section per executed outline with examples in
|
|
66
|
+
Messages input.
|
|
67
|
+
|
|
68
|
+
**Examples block** — one Examples table under a scenario outline, with its own
|
|
69
|
+
name, tags and description. An outline can have several.
|
|
70
|
+
|
|
71
|
+
**Example row** — one executed row of an examples block, labelled
|
|
72
|
+
`#<examples>.<example>` in the report. Each row keeps its own outcome,
|
|
73
|
+
attachments and anchor.
|
|
74
|
+
|
|
75
|
+
**Executed scenario** — a scenario whose selected test case reported at least
|
|
76
|
+
one raw step result, including a hook result. Only executed scenarios appear in
|
|
77
|
+
scenario counts, percentages, bars, triage and the Details matrix.
|
|
78
|
+
|
|
79
|
+
**Unexecuted scenario** — a scenario whose selected test case started but
|
|
80
|
+
reported no raw step result, including a started-but-unfinished case. It stays
|
|
81
|
+
visible without an outcome, keeps `status: "unknown"` and `executed: false` in
|
|
82
|
+
the summary, and leaves every count surface. Any attachment emitted for it is
|
|
83
|
+
dropped. A never-started pickle produces no row at all.
|
|
84
|
+
|
|
85
|
+
**Rule** — a Gherkin grouping of scenarios and outlines under a named business
|
|
86
|
+
rule. The report renders a rule section with its keyword, name, description and
|
|
87
|
+
tags; scenarios stay inside their rule.
|
|
88
|
+
|
|
89
|
+
**Background** — shared setup steps for a feature or rule. Cucumber compiles
|
|
90
|
+
them into each pickle, so the report keeps the steps in the scenario step lists
|
|
91
|
+
and renders only the background heading and description once, when present.
|
|
92
|
+
|
|
93
|
+
**Description** — free-text Markdown under a feature, rule, background,
|
|
94
|
+
scenario, outline or examples block. The report renders a safe GFM subset in a
|
|
95
|
+
block container; images become alt text and raw HTML stays escaped.
|
|
96
|
+
|
|
97
|
+
**Tag expression** — the official Cucumber boolean tag query (`@a and not @b`,
|
|
98
|
+
`or`, `not`, parentheses, escaped tags). The search box uses it only when the
|
|
99
|
+
whole query is tag-shaped; mixed text and tags fall back to substring search.
|
|
100
|
+
|
|
101
|
+
**URL state** — the shareable `?query=`, repeated lowercase `?hide=` and `?tag=`
|
|
102
|
+
parameters. The report restores them and updates them with `replaceState`
|
|
103
|
+
without adding history entries.
|
|
104
|
+
|
|
105
|
+
**Own tag** — a tag written on the scenario itself; for an outline row, the
|
|
106
|
+
examples-block tags. A standalone scenario row shows its own tags. Outline
|
|
107
|
+
scenario tags appear on the outline heading and examples tags on the examples
|
|
108
|
+
heading; example rows show no tags.
|
|
109
|
+
|
|
110
|
+
**Inherited tag** — a feature or rule tag carried into a pickle. It stays
|
|
111
|
+
available to the tag filter and search but is not repeated on every row.
|
|
112
|
+
|
|
113
|
+
**Hook** — a Cucumber before/after function around a scenario or step. The
|
|
114
|
+
report shows per-scenario hooks separately from steps.
|
|
115
|
+
|
|
116
|
+
**Test-run hook** — a BeforeAll/AfterAll function around the whole run. It
|
|
117
|
+
appears in the report's Hooks section, not inside a scenario.
|
|
118
|
+
|
|
119
|
+
**Step diagnostic** — the block inside an undefined or ambiguous step. It
|
|
120
|
+
always shows the status lead and adds suggestion snippets or matching step
|
|
121
|
+
definitions when the Messages input provides them.
|
|
122
|
+
|
|
123
|
+
**Snippet** — the suggested step-definition code from a Messages `suggestion`
|
|
124
|
+
envelope, shown escaped inside an undefined step.
|
|
125
|
+
|
|
126
|
+
**Step definition match** — a `stepDefinition` pattern and its `uri:line`
|
|
127
|
+
source reference, shown inside an ambiguous step.
|
|
128
|
+
|
|
129
|
+
**Auto-expansion** — the report opens features and executed scenarios whose
|
|
130
|
+
status is not `passed` by default. Passed scenarios stay collapsed unless they
|
|
131
|
+
carry an image; unexecuted rows stay collapsed and show no outcome. A feature
|
|
132
|
+
whose scenarios are all unexecuted opens; a mixed feature does not open just
|
|
133
|
+
because it contains an unexecuted row. Text search and a valid tag expression
|
|
134
|
+
still open at most 20 rows.
|
|
135
|
+
|
|
43
136
|
**Provenance** — the input file a feature came from. Tolkira only uses it when
|
|
44
137
|
the feature URI belongs to exactly one input; shared or missing provenance
|
|
45
138
|
renders a flat report.
|
package/README.md
CHANGED
|
@@ -6,7 +6,7 @@ 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
|
stay inside the file. There is no server, no CDN and no telemetry.
|
|
8
8
|
|
|
9
|
-
Current release: **v0.
|
|
9
|
+
Current release: **v0.3.0** - [npm](https://www.npmjs.com/package/tolkira) - [Changelog](https://github.com/Silasoa/tolkira/blob/main/docs/CHANGELOG.md)
|
|
10
10
|
|
|
11
11
|
> **How this is built:** Tolkira is human-directed and largely AI-generated.
|
|
12
12
|
> The maintainer sets the product direction and approves releases. Most code,
|
|
@@ -18,17 +18,23 @@ Current release: **v0.2.0** · [npm](https://www.npmjs.com/package/tolkira) · [
|
|
|
18
18
|
|
|
19
19
|
## Install
|
|
20
20
|
|
|
21
|
+
Tolkira requires Node.js 22 or newer.
|
|
22
|
+
|
|
21
23
|
```shell
|
|
24
|
+
# CLI for one-off use
|
|
22
25
|
npm install --global tolkira
|
|
23
26
|
tolkira --help
|
|
24
27
|
```
|
|
25
28
|
|
|
26
|
-
Or
|
|
29
|
+
Or add it to a project and run it from there (recommended for CI):
|
|
27
30
|
|
|
28
31
|
```shell
|
|
32
|
+
npm install --save-dev tolkira
|
|
29
33
|
npx tolkira --help
|
|
30
34
|
```
|
|
31
35
|
|
|
36
|
+
`npx tolkira --help` also works without a local install.
|
|
37
|
+
|
|
32
38
|
On Windows, `npx` can fail when the current folder contains parentheses in its
|
|
33
39
|
path. Use the global install or a folder without parentheses if that happens.
|
|
34
40
|
|
|
@@ -52,14 +58,76 @@ tolkira test-results/ --out report.html --logo path/to/logo.png
|
|
|
52
58
|
Tolkira accepts one or more files and directories. A directory is scanned
|
|
53
59
|
recursively for supported result files. Everything is merged into one report.
|
|
54
60
|
|
|
55
|
-
For
|
|
56
|
-
|
|
61
|
+
## For agents and CI
|
|
62
|
+
|
|
63
|
+
Install as a project dependency and write both artifacts:
|
|
57
64
|
|
|
58
65
|
```shell
|
|
59
|
-
|
|
60
|
-
tolkira test-results/ --json
|
|
66
|
+
npm install --save-dev tolkira
|
|
67
|
+
npx tolkira test-results/ --out report.html --title "CI run" --json > summary.json
|
|
61
68
|
```
|
|
62
69
|
|
|
70
|
+
GitHub Actions step:
|
|
71
|
+
|
|
72
|
+
```yaml
|
|
73
|
+
- name: Generate Cucumber report
|
|
74
|
+
if: always()
|
|
75
|
+
run: npx tolkira test-results/ --out report.html --title "CI run" --json > summary.json
|
|
76
|
+
|
|
77
|
+
- name: Upload report
|
|
78
|
+
if: always()
|
|
79
|
+
uses: actions/upload-artifact@v4
|
|
80
|
+
with:
|
|
81
|
+
name: cucumber-report
|
|
82
|
+
path: |
|
|
83
|
+
report.html
|
|
84
|
+
summary.json
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
`--json` writes exactly one JSON document to stdout; warnings go to stderr.
|
|
88
|
+
Exit code 0 means the report was generated, not that the tests passed. Read
|
|
89
|
+
`status` and `counts` from the summary. Abridged real output (counts and steps
|
|
90
|
+
trimmed):
|
|
91
|
+
|
|
92
|
+
```json
|
|
93
|
+
{
|
|
94
|
+
"schemaVersion": 2,
|
|
95
|
+
"status": "failed",
|
|
96
|
+
"counts": {
|
|
97
|
+
"scenarios": { "total": 6, "passed": 5, "failed": 1 }
|
|
98
|
+
},
|
|
99
|
+
"scenarios": [
|
|
100
|
+
{
|
|
101
|
+
"name": "Fred wants to see passing scenarios in the HTML report",
|
|
102
|
+
"uri": "features/happy.feature",
|
|
103
|
+
"status": "failed",
|
|
104
|
+
"executed": true,
|
|
105
|
+
"steps": [
|
|
106
|
+
{
|
|
107
|
+
"keyword": "When",
|
|
108
|
+
"text": "this feature runs with background",
|
|
109
|
+
"status": "failed",
|
|
110
|
+
"message": "Expected values to be strictly equal: -8 !== 0"
|
|
111
|
+
}
|
|
112
|
+
]
|
|
113
|
+
}
|
|
114
|
+
]
|
|
115
|
+
}
|
|
116
|
+
```
|
|
117
|
+
|
|
118
|
+
Paste this into an agent's instructions:
|
|
119
|
+
|
|
120
|
+
```text
|
|
121
|
+
Use Tolkira for Cucumber results. Run `npx tolkira <inputs> --out report.html --json`
|
|
122
|
+
and parse stdout as the JSON summary; do not scrape the HTML. Exit code 0 means
|
|
123
|
+
the report was generated, not that the tests passed. Read summary.status and
|
|
124
|
+
summary.counts, and check scenarios[].executed before treating a status as an
|
|
125
|
+
outcome. Upload report.html as the human-facing artifact.
|
|
126
|
+
```
|
|
127
|
+
|
|
128
|
+
See [`docs/AGENT-INTERFACE.md`](https://github.com/Silasoa/tolkira/blob/main/docs/AGENT-INTERFACE.md)
|
|
129
|
+
for the full schema and exit codes.
|
|
130
|
+
|
|
63
131
|
## What you get
|
|
64
132
|
|
|
65
133
|
- **One file that works offline.** CSS, JavaScript and attachments are inline.
|
|
@@ -75,6 +143,19 @@ tolkira test-results/ --json
|
|
|
75
143
|
files are preserved through the legacy JSON adapter.
|
|
76
144
|
- **Search and filters.** Search scenarios, features, steps and tags; filter by
|
|
77
145
|
status and tag; open matching features automatically and highlight matches.
|
|
146
|
+
- **Rendered descriptions.** Feature, rule, background, scenario and examples
|
|
147
|
+
descriptions render a safe GFM subset - headings, emphasis, code, lists,
|
|
148
|
+
tables, quotes and http(s)/mailto links - from Messages, legacy JSON and JUnit.
|
|
149
|
+
- **Tag expressions.** Search accepts the official Cucumber grammar
|
|
150
|
+
(`@a and not @b`, parentheses, escaped tags). Mixed text and tags fall back to
|
|
151
|
+
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.
|
|
154
|
+
- **Parameter highlighting.** Matched step arguments render with their Cucumber
|
|
155
|
+
parameter type from Messages; ambiguous or unmatched steps stay plain.
|
|
156
|
+
- **Messages stream adapter.** `CucumberHtmlStream` is shape-compatible with the
|
|
157
|
+
official formatter: it accepts envelopes, buffers until flush and emits the
|
|
158
|
+
same offline HTML as `renderReport`, for embedding without a temp file.
|
|
78
159
|
- **Copy failure.** Copy a failed scenario's feature, failed step and error as
|
|
79
160
|
plain text for a ticket or an agent.
|
|
80
161
|
- **A Details view when you need it.** Status distribution, a feature-by-status
|
|
@@ -93,7 +174,7 @@ tolkira test-results/ --json
|
|
|
93
174
|
|
|
94
175
|
| Input | What works |
|
|
95
176
|
| --- | --- |
|
|
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
|
|
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. |
|
|
97
178
|
| **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
179
|
| **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. |
|
|
99
180
|
|
|
@@ -124,6 +205,27 @@ can produce one file. Tolkira's difference is the combination - both Cucumber
|
|
|
124
205
|
generations, JUnit as cheap breadth, an agent-readable summary, and no server,
|
|
125
206
|
CDN or telemetry.
|
|
126
207
|
|
|
208
|
+
### What parity means here
|
|
209
|
+
|
|
210
|
+
"Parity" in this project means content and navigation: the same statements,
|
|
211
|
+
steps, tags, statuses, durations and descriptions, plus search, tag expressions
|
|
212
|
+
and shareable filter URLs, whether the input is legacy JSON, Messages or JUnit.
|
|
213
|
+
It does not mean theme parity with `cucumber-html-reporter`, a report folder, or
|
|
214
|
+
external attachments; Tolkira deliberately stays one offline file. The honest
|
|
215
|
+
claim is credible Messages report parity, not full formatter parity.
|
|
216
|
+
|
|
217
|
+
### How it compares
|
|
218
|
+
|
|
219
|
+
Last checked 2026-11-11 against the current package docs. Trade-offs are
|
|
220
|
+
deliberate; pick the tool that fits the job.
|
|
221
|
+
|
|
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.** |
|
|
228
|
+
|
|
127
229
|
The visual comparison uses the report setup from
|
|
128
230
|
[Seed-Test](https://github.com/adessoSE/Seed-Test). If you are curious about
|
|
129
231
|
Seed-Test, you are welcome to take a look; the comparison notes and screenshots
|
|
@@ -131,13 +233,36 @@ are in [`docs/COMPARISON.md`](https://github.com/Silasoa/tolkira/blob/main/docs/
|
|
|
131
233
|
|
|
132
234
|
## Migrating from cucumber-html-reporter
|
|
133
235
|
|
|
134
|
-
|
|
236
|
+
Install Tolkira next to the old reporter and keep the existing JSON output:
|
|
237
|
+
|
|
238
|
+
```shell
|
|
239
|
+
npm i -D tolkira
|
|
240
|
+
```
|
|
241
|
+
|
|
242
|
+
Node.js 22 or newer is required. Node 20 is end-of-life and unsupported;
|
|
243
|
+
upgrading to Node 22+ is the migration cost for both the ESM and CommonJS
|
|
244
|
+
paths. The core and CLI are ESM-only; the compatibility subpath also loads
|
|
245
|
+
from CommonJS through an async wrapper.
|
|
246
|
+
|
|
247
|
+
**Before — CommonJS with cucumber-html-reporter:**
|
|
135
248
|
|
|
136
249
|
```js
|
|
137
|
-
//
|
|
250
|
+
// report.js
|
|
138
251
|
const reporter = require('cucumber-html-reporter');
|
|
139
252
|
|
|
140
|
-
|
|
253
|
+
reporter.generate({
|
|
254
|
+
theme: 'bootstrap',
|
|
255
|
+
jsonFile: 'reports/cucumber.json',
|
|
256
|
+
output: 'reports/report.html',
|
|
257
|
+
brandTitle: 'Checkout acceptance',
|
|
258
|
+
metadata: { Browser: 'Chrome', Environment: 'Staging' },
|
|
259
|
+
});
|
|
260
|
+
```
|
|
261
|
+
|
|
262
|
+
**After — ESM with Tolkira:**
|
|
263
|
+
|
|
264
|
+
```js
|
|
265
|
+
// report.mjs
|
|
141
266
|
import { generate } from 'tolkira/compat/cucumber-html-reporter';
|
|
142
267
|
|
|
143
268
|
await generate({
|
|
@@ -148,11 +273,71 @@ await generate({
|
|
|
148
273
|
});
|
|
149
274
|
```
|
|
150
275
|
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
276
|
+
**If the project must stay CommonJS**, require the compatibility subpath and
|
|
277
|
+
await the async wrapper:
|
|
278
|
+
|
|
279
|
+
```js
|
|
280
|
+
// report.cjs
|
|
281
|
+
const { generate } = require('tolkira/compat/cucumber-html-reporter');
|
|
282
|
+
|
|
283
|
+
async function main() {
|
|
284
|
+
await generate({
|
|
285
|
+
jsonFile: 'reports/cucumber.json',
|
|
286
|
+
output: 'reports/report.html',
|
|
287
|
+
});
|
|
288
|
+
}
|
|
289
|
+
|
|
290
|
+
main().catch((error) => {
|
|
291
|
+
console.error(error);
|
|
292
|
+
process.exitCode = 1;
|
|
293
|
+
});
|
|
294
|
+
```
|
|
295
|
+
|
|
296
|
+
The wrapper is only for the compatibility subpath; the core package, CLI and
|
|
297
|
+
other exports remain ESM-only. There is no default export.
|
|
298
|
+
|
|
299
|
+
The options object is mostly compatible, but the call contract is not. Only
|
|
300
|
+
the import style changing is not the whole story:
|
|
301
|
+
|
|
302
|
+
| Behaviour | `cucumber-html-reporter` | Tolkira compat shim |
|
|
303
|
+
| --- | --- | --- |
|
|
304
|
+
| Input | `jsonFile` falls back to `output + '.json'` when omitted | `jsonFile` or `jsonDir` is required; there is no implicit fallback |
|
|
305
|
+
| 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
|
+
| 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
|
+
| 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 |
|
|
309
|
+
| Output timing | The HTML is written synchronously before `generate` returns | The HTML is complete only when the promise resolves |
|
|
310
|
+
| Export | `require('cucumber-html-reporter').generate` | Named `generate`; no default export |
|
|
311
|
+
|
|
312
|
+
**Callback caveat:** callback-only code can ignore the returned promise.
|
|
313
|
+
Tolkira marks that ignored promise handled so it does not crash the process;
|
|
314
|
+
awaiting the same call still throws. Errors are `Error` objects, not the
|
|
315
|
+
legacy strings. If the callback itself throws, handle that error yourself.
|
|
316
|
+
|
|
317
|
+
`theme` is ignored with a warning. Themes, charts, external screenshots and
|
|
318
|
+
browser launch are not reproduced. The shim consumes the same input JSON,
|
|
319
|
+
never the old rendered HTML.
|
|
320
|
+
See [`docs/COMPATIBILITY.md`](https://github.com/Silasoa/tolkira/blob/main/docs/COMPATIBILITY.md)
|
|
321
|
+
for the full mapping and caveats.
|
|
322
|
+
|
|
323
|
+
### From multiple-cucumber-html-reporter
|
|
324
|
+
|
|
325
|
+
There is no MCHR shim; use the core CLI. The common mapping:
|
|
326
|
+
|
|
327
|
+
```shell
|
|
328
|
+
# MCHR config: jsonDir + reportPath + reportName
|
|
329
|
+
mchr
|
|
330
|
+
|
|
331
|
+
# Tolkira
|
|
332
|
+
npx tolkira path/to/jsonDir --out reports/index.html --title "My report"
|
|
333
|
+
```
|
|
334
|
+
|
|
335
|
+
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
|
|
339
|
+
[`docs/COMPATIBILITY.md`](https://github.com/Silasoa/tolkira/blob/main/docs/COMPATIBILITY.md#multiple-cucumber-html-reporter)
|
|
340
|
+
for the mapping.
|
|
156
341
|
|
|
157
342
|
## Privacy and limits
|
|
158
343
|
|
|
@@ -166,10 +351,17 @@ caveats.
|
|
|
166
351
|
- One report is one file. External attachments for very large media are a
|
|
167
352
|
future option.
|
|
168
353
|
|
|
354
|
+
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.
|
|
357
|
+
|
|
169
358
|
## Documentation
|
|
170
359
|
|
|
360
|
+
- [`llms.txt`](https://github.com/Silasoa/tolkira/blob/main/llms.txt) — short entry point for AI agents.
|
|
171
361
|
- [`docs/AGENT-INTERFACE.md`](https://github.com/Silasoa/tolkira/blob/main/docs/AGENT-INTERFACE.md) — JSON schema, CLI
|
|
172
362
|
contract and exit codes.
|
|
363
|
+
- [`docs/LIMITATIONS.md`](https://github.com/Silasoa/tolkira/blob/main/docs/LIMITATIONS.md) — dated limitations table
|
|
364
|
+
(last verified 2026-11-11).
|
|
173
365
|
- [`docs/CUCUMBER-COMPATIBILITY.md`](https://github.com/Silasoa/tolkira/blob/main/docs/CUCUMBER-COMPATIBILITY.md) — tested
|
|
174
366
|
Cucumber producers and versions.
|
|
175
367
|
- [`docs/JUNIT-XML.md`](https://github.com/Silasoa/tolkira/blob/main/docs/JUNIT-XML.md) — JUnit basic-mode mapping and
|
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.
|