tolkira 0.0.0-stage → 0.1.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/DESIGN.md +178 -0
- package/GLOSSARY.md +60 -0
- package/LICENSE +21 -0
- package/README.md +233 -2
- package/SECURITY.md +30 -0
- package/dist/cli.d.ts +5 -0
- package/dist/cli.js +3097 -0
- package/dist/cli.js.map +7 -0
- package/dist/compat/cucumber-html-reporter.d.ts +7 -0
- package/dist/compat/cucumber-html-reporter.js +187 -0
- package/dist/compat/cucumber-html-reporter.js.map +7 -0
- package/dist/compat/options.d.ts +30 -0
- package/dist/index.d.ts +17 -0
- package/dist/index.js +2877 -0
- package/dist/index.js.map +7 -0
- package/dist/input/files.d.ts +2 -0
- package/dist/input/junit.d.ts +3 -0
- package/dist/input/legacy.d.ts +8 -0
- package/dist/input/load.d.ts +2 -0
- package/dist/input/messages.d.ts +3 -0
- package/dist/input/sanitize.d.ts +7 -0
- package/dist/output.d.ts +1 -0
- package/dist/render/escape.d.ts +1 -0
- package/dist/render/html.d.ts +10 -0
- package/dist/render/styles.d.ts +1 -0
- package/dist/report/model.d.ts +81 -0
- package/dist/result-message.d.ts +6 -0
- package/dist/summary.d.ts +52 -0
- package/dist/validation.d.ts +3 -0
- package/docs/AGENT-INTERFACE.md +179 -0
- package/docs/COMPATIBILITY.md +98 -0
- package/docs/CUCUMBER-COMPATIBILITY.md +102 -0
- package/docs/JUNIT-XML.md +77 -0
- package/package.json +83 -4
package/DESIGN.md
ADDED
|
@@ -0,0 +1,178 @@
|
|
|
1
|
+
# Tolkira report design system
|
|
2
|
+
|
|
3
|
+
**Mode:** Operate. The report is a work surface for developers and QA, not a
|
|
4
|
+
landing page. The tool disappears into the task: find the failure, read the
|
|
5
|
+
error, inspect the screenshot, move on.
|
|
6
|
+
|
|
7
|
+
## Product job
|
|
8
|
+
|
|
9
|
+
Answer five questions in under thirty seconds:
|
|
10
|
+
|
|
11
|
+
1. Did everything pass?
|
|
12
|
+
2. What failed, and why?
|
|
13
|
+
3. What did it look like?
|
|
14
|
+
4. Can I find the relevant scenario?
|
|
15
|
+
5. Can I share one file with someone else?
|
|
16
|
+
|
|
17
|
+
The default report is simple and failed-first. Deeper analysis belongs in the
|
|
18
|
+
optional Details view, never in the way of the failure.
|
|
19
|
+
|
|
20
|
+
## Principles
|
|
21
|
+
|
|
22
|
+
- **One file, no network.** All CSS, scripts and attachments are inline. No
|
|
23
|
+
CDN, no remote font, no telemetry.
|
|
24
|
+
- **Status is text, not only colour.** Every status has a label; colour is a
|
|
25
|
+
second signal.
|
|
26
|
+
- **Evidence first.** A screenshot or attachment is part of the failure, not
|
|
27
|
+
decoration.
|
|
28
|
+
- **Native disclosure.** Use `<details>`/`<summary>` with a visible chevron;
|
|
29
|
+
search and filters open the features that contain matches.
|
|
30
|
+
- **Density with air.** Compact rows, but never cramped; 0.9375 rem body,
|
|
31
|
+
0.75–0.875 rem metadata, 0.6875 rem minimum for functional text.
|
|
32
|
+
- **Accessible by default.** WCAG 2.2 AA, keyboard focus, reduced motion,
|
|
33
|
+
200 % page zoom and 200 % text zoom, no colour-only status, no horizontal
|
|
34
|
+
page scroll.
|
|
35
|
+
|
|
36
|
+
## Tokens
|
|
37
|
+
|
|
38
|
+
The source of truth is `src/render/styles.ts` (generated from the report CSS).
|
|
39
|
+
Use the token names, never raw colours.
|
|
40
|
+
|
|
41
|
+
| Token | Role |
|
|
42
|
+
| --- | --- |
|
|
43
|
+
| `--paper` | Page surface |
|
|
44
|
+
| `--canvas` | Page background |
|
|
45
|
+
| `--surface-2` | Secondary surface, row hover, panels |
|
|
46
|
+
| `--ink` | Primary text |
|
|
47
|
+
| `--muted` | Secondary text, labels, captions |
|
|
48
|
+
| `--line`, `--line-strong` | Hairline rules and control borders |
|
|
49
|
+
| `--accent`, `--accent-soft` | Brand, current selection, primary action |
|
|
50
|
+
| `--pass`, `--pass-soft` | Passed |
|
|
51
|
+
| `--fail`, `--fail-soft` | Failed |
|
|
52
|
+
| `--pending`, `--pending-soft` | Pending |
|
|
53
|
+
| `--undefined`, `--undefined-soft` | Undefined / missing step definition |
|
|
54
|
+
| `--skipped`, `--skipped-soft` | Skipped |
|
|
55
|
+
| `--radius`, `--shadow` | Panel radius and one elevation |
|
|
56
|
+
|
|
57
|
+
Dark mode is a token override under `prefers-color-scheme: dark`; it never
|
|
58
|
+
changes layout.
|
|
59
|
+
|
|
60
|
+
## Type
|
|
61
|
+
|
|
62
|
+
- System sans for body and display; system mono only for measurements,
|
|
63
|
+
durations, file paths and error text.
|
|
64
|
+
- Body 0.9375 rem, line-height 1.5–1.55.
|
|
65
|
+
- Row title 0.8125–0.875 rem/600; metadata 0.6875–0.75 rem; step text
|
|
66
|
+
0.75–0.8125 rem.
|
|
67
|
+
- Sentence case everywhere. No tracked capitals, no emoji icons.
|
|
68
|
+
- No fluid display headings in the report shell; fixed rem steps.
|
|
69
|
+
|
|
70
|
+
### Why rem, not fluid type
|
|
71
|
+
|
|
72
|
+
`rem` ties every text size to the root font size, so the browser's
|
|
73
|
+
font-size setting and text-only zoom actually work. Fluid `clamp()`/`vw`
|
|
74
|
+
typography is for marketing pages: in a dense report it makes text small on
|
|
75
|
+
phones and unpredictable at 200 % zoom.
|
|
76
|
+
|
|
77
|
+
Fixed `px` stays only where it is not text: 1 px hairlines, focus-ring
|
|
78
|
+
thickness, radii and the 1320 px page frame. Spacing, control heights, icon
|
|
79
|
+
size, thumbnails and the fixed thumbnail gutter use `rem` so they grow with
|
|
80
|
+
the text they sit next to. Media-query breakpoints stay in `px` because they
|
|
81
|
+
describe the viewport, not the font.
|
|
82
|
+
|
|
83
|
+
## Responsive
|
|
84
|
+
|
|
85
|
+
- Layout responds through content-driven primitives: `minmax()`, `flex-wrap`,
|
|
86
|
+
`max-width`, two breakpoints (900 px, 560 px) and container queries at
|
|
87
|
+
`16rem`. No fixed page width.
|
|
88
|
+
- The 720 × 450 browser test is **200 % page zoom** at a 1440 × 900 window, not
|
|
89
|
+
a hardcoded layout size. 320 px and 390 px are separate phone checks.
|
|
90
|
+
- Text zoom is tested by doubling the root font size; the layout must reflow
|
|
91
|
+
without horizontal page scroll. At `16rem` container width the feature and
|
|
92
|
+
scenario rows stack and the run title steps down, so text zoom keeps a
|
|
93
|
+
readable title column instead of squeezing it to zero.
|
|
94
|
+
- The shell is a document, not an app canvas: it has no viewport-height frame
|
|
95
|
+
and no horizontal scroll region except tables and code blocks. Every
|
|
96
|
+
horizontal scroll region is focusable (`tabindex="0"`, `role="region"`,
|
|
97
|
+
accessible name) so keyboard users can reach clipped columns.
|
|
98
|
+
|
|
99
|
+
## Components
|
|
100
|
+
|
|
101
|
+
| Component | File / selector | Rule |
|
|
102
|
+
| --- | --- | --- |
|
|
103
|
+
| Top bar / tabs | `.topbar`, `.view` | Report and Details; active tab is a text state, not a card |
|
|
104
|
+
| Run header | `.runHead`, `.health` | Title, metadata, pass rate, segmented status bar |
|
|
105
|
+
| Toolbar | `.toolbar`, `.search`, `.filter` | Search and status filters; search opens matching features and scenarios; filters only for present statuses |
|
|
106
|
+
| Feature | `details.feature` | Native disclosure; status, name, path, counts, duration |
|
|
107
|
+
| Scenario | `details.scenario` | Fixed thumbnail gutter, status, name, tags, steps, duration |
|
|
108
|
+
| Step | `.step` | Status glyph plus screen-reader label, keyword, text, error, doc string, focusable table, attachments |
|
|
109
|
+
| Attachment | `.shot`, `.fileText`, `.fileLink` | Images inline; text in `<pre>`; binary as download; alt names the scenario and step |
|
|
110
|
+
| Details | `.analysis` | Feature table, status distribution, Run / Cucumber environment / Custom metadata blocks, agent summary |
|
|
111
|
+
|
|
112
|
+
## Interaction rules
|
|
113
|
+
|
|
114
|
+
- Feature and scenario summaries are the only click targets that toggle; a
|
|
115
|
+
click inside the detail does not close it.
|
|
116
|
+
- Chevron rotates on open; `prefers-reduced-motion` removes the transition.
|
|
117
|
+
- Search and filters: hide non-matches, open features and matched scenarios,
|
|
118
|
+
update a polite live region, show an empty state when nothing matches.
|
|
119
|
+
- Switching tabs scrolls to the top; the previous panel's scroll position is
|
|
120
|
+
not restored.
|
|
121
|
+
- The lightbox locks background scrolling, restores focus to its trigger on
|
|
122
|
+
Escape, Close, backdrop click and padding click, and reserves header space so
|
|
123
|
+
Close never covers the screenshot.
|
|
124
|
+
- Status is never colour-only: scenario badges carry text, step markers carry a
|
|
125
|
+
shape glyph plus a screen-reader label, and forced-colours mode keeps the
|
|
126
|
+
glyph, marker border and disclosure chevron visible.
|
|
127
|
+
- The failure is open by default; everything else is scannable when collapsed.
|
|
128
|
+
- No right-click-only actions; use visible buttons or a `…` menu. Keyboard and
|
|
129
|
+
touch must reach the same actions.
|
|
130
|
+
- No modal for a task that inline disclosure can solve.
|
|
131
|
+
|
|
132
|
+
## Styling policy
|
|
133
|
+
|
|
134
|
+
**Plain CSS with tokens, not Tailwind.** The report is generated as one HTML
|
|
135
|
+
string with inline CSS; Tailwind would add a build step, content scanning of
|
|
136
|
+
TypeScript template strings, and safelists for dynamic status classes. The
|
|
137
|
+
report has ~20 components and a 15 KB stylesheet. A small, explicit token
|
|
138
|
+
system is easier for agents to read, test and change than utility soup in
|
|
139
|
+
template strings. A local utility layer is fine when it removes repetition.
|
|
140
|
+
|
|
141
|
+
## Agent workflow
|
|
142
|
+
|
|
143
|
+
1. Read `docs/PRODUCT.md`, this file, `src/report/model.ts`,
|
|
144
|
+
`src/render/html.ts` and `src/render/styles.ts`.
|
|
145
|
+
2. Change the view model first if the data is missing; keep `src/summary.ts`
|
|
146
|
+
independent.
|
|
147
|
+
3. Use tokens and existing component classes; do not add a UI framework.
|
|
148
|
+
4. Add a unit test for the model/HTML and a browser test for the interaction.
|
|
149
|
+
5. Render a real fixture at 1440×900 and 390×844; check focus, overflow,
|
|
150
|
+
reduced motion, 200 % text zoom and dark mode.
|
|
151
|
+
6. Run `npm run check` and `npm run test:e2e`.
|
|
152
|
+
7. For a new visual world, use the Hallmark/Impeccable loop in
|
|
153
|
+
`docs/ui-loop/`; for a normal change, stay inside this system.
|
|
154
|
+
|
|
155
|
+
## Current status
|
|
156
|
+
|
|
157
|
+
Direction A is implemented in production:
|
|
158
|
+
|
|
159
|
+
- warm paper tokens, hairline sections and monospace measurements;
|
|
160
|
+
- fixed thumbnail gutter on every scenario row, also on mobile;
|
|
161
|
+
- chevrons, failed-first disclosures and search that opens matching features;
|
|
162
|
+
- `undefined` is a distinct status, not a neutral one;
|
|
163
|
+
- Details tab with producer, runtime, OS, CPU, protocol and user metadata;
|
|
164
|
+
- empty state for search/filter results;
|
|
165
|
+
- screenshot lightbox with a close button and Escape support.
|
|
166
|
+
|
|
167
|
+
CSS lives in `src/render/report.css`; `scripts/build-styles.mjs` generates
|
|
168
|
+
`src/render/styles.ts` for the inline report.
|
|
169
|
+
|
|
170
|
+
Still open: a 200 % text-zoom pass with real content, and charts/trends in
|
|
171
|
+
Advanced.
|
|
172
|
+
|
|
173
|
+
## Non-goals
|
|
174
|
+
|
|
175
|
+
- React, Tailwind, Bootstrap, jQuery, CDN fonts or charts.
|
|
176
|
+
- Old reporter themes.
|
|
177
|
+
- A server, watch mode, telemetry or test-management workflows.
|
|
178
|
+
- Right-click-only context menus.
|
package/GLOSSARY.md
ADDED
|
@@ -0,0 +1,60 @@
|
|
|
1
|
+
# Glossary
|
|
2
|
+
|
|
3
|
+
**Tolkira** — the project and CLI. Coined from Scandinavian *tolk*
|
|
4
|
+
(interpreter).
|
|
5
|
+
|
|
6
|
+
**Report** — one self-contained HTML file generated from one or more test
|
|
7
|
+
result inputs.
|
|
8
|
+
|
|
9
|
+
**Legacy JSON** — the older Cucumber JSON output format. Implementation-specific
|
|
10
|
+
and lossy, but still widely used.
|
|
11
|
+
|
|
12
|
+
**Messages / Envelopes** — Cucumber Messages, the modern NDJSON envelope stream
|
|
13
|
+
used by official Cucumber implementations.
|
|
14
|
+
|
|
15
|
+
**Attachment** — a binary or text artefact attached to a test step, scenario or
|
|
16
|
+
hook. Screenshots are attachments.
|
|
17
|
+
|
|
18
|
+
**Embedding** — the legacy JSON representation of an attachment (`embeddings[]`).
|
|
19
|
+
|
|
20
|
+
**Adapter** — code that turns an input format into Cucumber Messages.
|
|
21
|
+
|
|
22
|
+
**Normalisation** — converting legacy JSON into Messages so one renderer can
|
|
23
|
+
handle both.
|
|
24
|
+
|
|
25
|
+
**Renderer** — Tolkira's server-side report renderer: it turns the report model
|
|
26
|
+
into HTML, CSS and a small script. It is part of Tolkira, not an upstream React
|
|
27
|
+
component tree.
|
|
28
|
+
|
|
29
|
+
**Shell** — Tolkira's own wrapper around the renderer: title, metadata, summary,
|
|
30
|
+
theme, logo.
|
|
31
|
+
|
|
32
|
+
**Summary** — the stable, renderer-independent JSON document emitted by
|
|
33
|
+
`--json` / `summarizeReport` for agents and CI. It is versioned and is not the
|
|
34
|
+
HTML report.
|
|
35
|
+
|
|
36
|
+
**Schema version** — the integer in `summary.schemaVersion`. A breaking change
|
|
37
|
+
increments it; consumers may reject versions they do not know.
|
|
38
|
+
|
|
39
|
+
**Fixture** — a small, real or realistic input file used by tests.
|
|
40
|
+
|
|
41
|
+
**Vertical slice** — a small end-to-end change: input → normalise → render →
|
|
42
|
+
output, with tests.
|
|
43
|
+
|
|
44
|
+
**Gate** — the required checks before merge: typecheck, lint, tests, build,
|
|
45
|
+
browser test.
|
|
46
|
+
|
|
47
|
+
**Blind review** — reviewers receive the spec and diff, not the implementer's
|
|
48
|
+
self-report.
|
|
49
|
+
|
|
50
|
+
**SCR** — Spec-Compliance Reviewer.
|
|
51
|
+
|
|
52
|
+
**CR** — Code Reviewer.
|
|
53
|
+
|
|
54
|
+
**DAR** — Documentation & Agent-Readability Reviewer.
|
|
55
|
+
|
|
56
|
+
**SEC** — Security Reviewer, triggered for input parsing, attachments, HTML
|
|
57
|
+
injection and file output.
|
|
58
|
+
|
|
59
|
+
**ISTQB edge cases** — test design using equivalence partitioning, boundary
|
|
60
|
+
values, decision tables and state transitions.
|
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Tolkira contributors
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,234 @@
|
|
|
1
|
-
#
|
|
1
|
+
# Tolkira
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
**One self-contained HTML report for Cucumber JSON, Messages and JUnit XML.**
|
|
4
|
+
|
|
5
|
+
Tolkira turns test results into a single HTML file you can open offline, attach
|
|
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.
|
|
8
|
+
|
|
9
|
+
Current release: **v0.1.1** · [npm](https://www.npmjs.com/package/tolkira) · [Changelog](https://github.com/Silasoa/tolkira/blob/main/docs/CHANGELOG.md)
|
|
10
|
+
|
|
11
|
+
> **How this is built:** Tolkira is human-directed and largely AI-generated.
|
|
12
|
+
> The maintainer sets the product direction, reviews changes, runs the release
|
|
13
|
+
> gate and makes release decisions. Most code, tests and documentation are
|
|
14
|
+
> drafted with large language models, then reviewed and tested by humans.
|
|
15
|
+
> AI output can be wrong; please check the report against your own results and
|
|
16
|
+
> open an issue if something looks off. [Read more](#how-this-project-is-built).
|
|
17
|
+
|
|
18
|
+
## Install
|
|
19
|
+
|
|
20
|
+
```shell
|
|
21
|
+
npm install --global tolkira
|
|
22
|
+
tolkira --help
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
Or run it without a global install:
|
|
26
|
+
|
|
27
|
+
```shell
|
|
28
|
+
npx tolkira --help
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
On Windows, `npx` can fail when the current folder contains parentheses in its
|
|
32
|
+
path. Use the global install or a folder without parentheses if that happens.
|
|
33
|
+
|
|
34
|
+
## Quick start
|
|
35
|
+
|
|
36
|
+
```shell
|
|
37
|
+
# One file, one report
|
|
38
|
+
tolkira test-results/ --out report.html --title "Checkout acceptance"
|
|
39
|
+
|
|
40
|
+
# Add your own metadata and brand colour
|
|
41
|
+
tolkira test-results/ --out report.html \
|
|
42
|
+
--title "Checkout acceptance" \
|
|
43
|
+
--meta "App version=0.3.2" \
|
|
44
|
+
--meta "Environment=Staging" \
|
|
45
|
+
--accent "#1b5e20"
|
|
46
|
+
|
|
47
|
+
# Embed a logo (PNG, JPEG, GIF, WebP or SVG)
|
|
48
|
+
tolkira test-results/ --out report.html --logo path/to/logo.png
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
Tolkira accepts one or more files and directories. A directory is scanned
|
|
52
|
+
recursively for supported result files. Everything is merged into one report.
|
|
53
|
+
|
|
54
|
+
For CI tools and AI agents, ask for the stable JSON summary instead of scraping
|
|
55
|
+
the HTML:
|
|
56
|
+
|
|
57
|
+
```shell
|
|
58
|
+
tolkira test-results/ --out report.html --json
|
|
59
|
+
tolkira test-results/ --json
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
## What you get
|
|
63
|
+
|
|
64
|
+
- **One file that works offline.** CSS, JavaScript and attachments are inline.
|
|
65
|
+
No network requests, no remote fonts, no analytics.
|
|
66
|
+
- **The failure first.** Failed scenarios are open by default, with the error
|
|
67
|
+
and screenshot where you need them.
|
|
68
|
+
- **Screenshots and attachments that survive.** Images, text, video, audio and
|
|
69
|
+
files are preserved through the legacy JSON adapter.
|
|
70
|
+
- **Search and filters.** Search scenarios, features, steps and tags; filter by
|
|
71
|
+
status and tag; open matching features automatically and highlight matches.
|
|
72
|
+
- **Copy failure.** Copy a failed scenario's feature, failed step and error as
|
|
73
|
+
plain text for a ticket or an agent.
|
|
74
|
+
- **A Details view when you need it.** Status distribution, a feature table,
|
|
75
|
+
run metadata and the Cucumber environment (producer, runtime, OS, CPU,
|
|
76
|
+
protocol).
|
|
77
|
+
- **A stable summary for agents.** `--json` and `summarizeReport()` return a
|
|
78
|
+
versioned schema with counts, durations, scenarios, steps and failure
|
|
79
|
+
messages.
|
|
80
|
+
- **Accessible by default.** Keyboard navigation, visible focus, text status
|
|
81
|
+
labels as well as colour, dark mode and 200% zoom reflow. Accessibility is an
|
|
82
|
+
ongoing effort; feedback is welcome.
|
|
83
|
+
- **Your branding.** Title, metadata, logo and accent colour without forking the
|
|
84
|
+
shell.
|
|
85
|
+
|
|
86
|
+
## Supported inputs
|
|
87
|
+
|
|
88
|
+
| Input | What works |
|
|
89
|
+
| --- | --- |
|
|
90
|
+
| **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. |
|
|
91
|
+
| **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. |
|
|
92
|
+
| **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. |
|
|
93
|
+
|
|
94
|
+
Multiple files and mixed formats can be merged into one run. See
|
|
95
|
+
[`docs/CUCUMBER-COMPATIBILITY.md`](https://github.com/Silasoa/tolkira/blob/main/docs/CUCUMBER-COMPATIBILITY.md) for the
|
|
96
|
+
tested producer matrix and
|
|
97
|
+
[`docs/JUNIT-XML.md`](https://github.com/Silasoa/tolkira/blob/main/docs/JUNIT-XML.md) for the JUnit limits.
|
|
98
|
+
|
|
99
|
+
## Why Tolkira exists
|
|
100
|
+
|
|
101
|
+
[`cucumber-html-reporter`](https://github.com/protractor-cucumber-framework/cucumber-html-reporter)
|
|
102
|
+
has been effectively unmaintained since October 2024. It still has a large
|
|
103
|
+
user base, but it loads Bootstrap, jQuery and Google Charts from CDNs, only
|
|
104
|
+
reads legacy JSON, and carries old runtime dependencies. Reports that should
|
|
105
|
+
work offline lose their layout and charts.
|
|
106
|
+
|
|
107
|
+
Tolkira keeps the old input working and fixes the parts that hurt:
|
|
108
|
+
|
|
109
|
+
- one offline file instead of CDN dependencies;
|
|
110
|
+
- legacy JSON **and** modern Messages;
|
|
111
|
+
- JUnit XML as cheap breadth for non-Cucumber teams;
|
|
112
|
+
- screenshots and attachments that stay in the report;
|
|
113
|
+
- a stable JSON summary for agents and CI;
|
|
114
|
+
- a small, reviewed dependency surface.
|
|
115
|
+
|
|
116
|
+
The visual comparison uses the report setup from
|
|
117
|
+
[Seed-Test](https://github.com/adessoSE/Seed-Test). If you are curious about
|
|
118
|
+
Seed-Test, you are welcome to take a look; the comparison notes and screenshots
|
|
119
|
+
are in [`docs/COMPARISON.md`](https://github.com/Silasoa/tolkira/blob/main/docs/COMPARISON.md).
|
|
120
|
+
|
|
121
|
+
## Migrating from cucumber-html-reporter
|
|
122
|
+
|
|
123
|
+
The old options object is accepted as-is; only the import changes.
|
|
124
|
+
|
|
125
|
+
```js
|
|
126
|
+
// before
|
|
127
|
+
const reporter = require('cucumber-html-reporter');
|
|
128
|
+
|
|
129
|
+
// after
|
|
130
|
+
import { generate } from 'tolkira/compat/cucumber-html-reporter';
|
|
131
|
+
|
|
132
|
+
await generate({
|
|
133
|
+
jsonFile: 'reports/cucumber.json',
|
|
134
|
+
output: 'reports/report.html',
|
|
135
|
+
brandTitle: 'Checkout acceptance',
|
|
136
|
+
metadata: { Browser: 'Chrome', Environment: 'Staging' },
|
|
137
|
+
});
|
|
138
|
+
```
|
|
139
|
+
|
|
140
|
+
The shim is experimental. Themes, charts, external screenshots and browser
|
|
141
|
+
launch are not reproduced; they warn and use Tolkira's defaults. It consumes
|
|
142
|
+
the same input JSON, never the old rendered HTML. See
|
|
143
|
+
[`docs/COMPATIBILITY.md`](https://github.com/Silasoa/tolkira/blob/main/docs/COMPATIBILITY.md) for the full mapping and
|
|
144
|
+
caveats.
|
|
145
|
+
|
|
146
|
+
## Privacy and limits
|
|
147
|
+
|
|
148
|
+
- No network requests, no telemetry, no remote fonts and no CDN.
|
|
149
|
+
- A restrictive Content Security Policy is embedded in every report.
|
|
150
|
+
- Test names, metadata and attachments are treated as untrusted input.
|
|
151
|
+
- Default limits: 100 MB total input, 50 MB per attachment and 100 MB total
|
|
152
|
+
attachments. A warning appears when a report grows beyond 10 MB.
|
|
153
|
+
- JUnit XML is intentionally basic; it is not a replacement for a native
|
|
154
|
+
Playwright, Jest or Allure report.
|
|
155
|
+
- One report is one file. External attachments for very large media are a
|
|
156
|
+
future option.
|
|
157
|
+
|
|
158
|
+
## Documentation
|
|
159
|
+
|
|
160
|
+
- [`docs/AGENT-INTERFACE.md`](https://github.com/Silasoa/tolkira/blob/main/docs/AGENT-INTERFACE.md) — JSON schema, CLI
|
|
161
|
+
contract and exit codes.
|
|
162
|
+
- [`docs/CUCUMBER-COMPATIBILITY.md`](https://github.com/Silasoa/tolkira/blob/main/docs/CUCUMBER-COMPATIBILITY.md) — tested
|
|
163
|
+
Cucumber producers and versions.
|
|
164
|
+
- [`docs/JUNIT-XML.md`](https://github.com/Silasoa/tolkira/blob/main/docs/JUNIT-XML.md) — JUnit basic-mode mapping and
|
|
165
|
+
limits.
|
|
166
|
+
- [`docs/COMPATIBILITY.md`](https://github.com/Silasoa/tolkira/blob/main/docs/COMPATIBILITY.md) — migration from
|
|
167
|
+
cucumber-html-reporter.
|
|
168
|
+
- [`docs/COMPARISON.md`](https://github.com/Silasoa/tolkira/blob/main/docs/COMPARISON.md) — Seed-Test comparison and
|
|
169
|
+
remaining parity gaps.
|
|
170
|
+
|
|
171
|
+
## Development
|
|
172
|
+
|
|
173
|
+
Tolkira requires Node.js 22 or newer.
|
|
174
|
+
|
|
175
|
+
```shell
|
|
176
|
+
npm install
|
|
177
|
+
npx playwright install chromium firefox webkit
|
|
178
|
+
npm run check
|
|
179
|
+
npm run test:e2e
|
|
180
|
+
npm run stress -- 1000
|
|
181
|
+
```
|
|
182
|
+
|
|
183
|
+
`npm run check` runs typecheck, lint, unit tests, build and the CSS generation
|
|
184
|
+
step. `npm run test:e2e` runs the browser tests in Chromium, Firefox and
|
|
185
|
+
WebKit. `npm run stress -- 1000` builds a 1,000-scenario report and reports size
|
|
186
|
+
and timing.
|
|
187
|
+
|
|
188
|
+
Build once and run the CLI from `dist`:
|
|
189
|
+
|
|
190
|
+
```shell
|
|
191
|
+
npm run build
|
|
192
|
+
node dist/cli.js test/fixtures/legacy/happy.json \
|
|
193
|
+
--out report.html \
|
|
194
|
+
--title "My report" \
|
|
195
|
+
--meta Browser=Chrome
|
|
196
|
+
```
|
|
197
|
+
|
|
198
|
+
## Contributing and feedback
|
|
199
|
+
|
|
200
|
+
Bug reports, accessibility feedback and compatibility fixtures are welcome.
|
|
201
|
+
If a producer or report shape does not work, a small sanitized fixture is the
|
|
202
|
+
most useful thing you can attach. Please do not include secrets or private test
|
|
203
|
+
data.
|
|
204
|
+
|
|
205
|
+
If you want to work on the code, start with [`AGENTS.md`](https://github.com/Silasoa/tolkira/blob/main/AGENTS.md), the
|
|
206
|
+
[`openspec/`](https://github.com/Silasoa/tolkira/tree/main/openspec) change contracts and
|
|
207
|
+
[`docs/agents/review.md`](https://github.com/Silasoa/tolkira/blob/main/docs/agents/review.md). Product and architecture
|
|
208
|
+
notes live in [`docs/PRODUCT.md`](https://github.com/Silasoa/tolkira/blob/main/docs/PRODUCT.md) and
|
|
209
|
+
[`docs/ARCHITECTURE.md`](https://github.com/Silasoa/tolkira/blob/main/docs/ARCHITECTURE.md).
|
|
210
|
+
|
|
211
|
+
## How this project is built
|
|
212
|
+
|
|
213
|
+
Tolkira is an experiment in AI-assisted open source. The maintainer defines the
|
|
214
|
+
problem, the scope and the design direction; large language models draft most of
|
|
215
|
+
the code, tests and documentation; the maintainer reviews, runs the test and
|
|
216
|
+
release gates, and makes the final release decision.
|
|
217
|
+
|
|
218
|
+
The project does not name specific models in its files on purpose. The
|
|
219
|
+
maintainer configures the models and tooling. This keeps the project
|
|
220
|
+
model-agnostic and avoids turning a temporary tool choice into a permanent
|
|
221
|
+
dependency.
|
|
222
|
+
|
|
223
|
+
AI-generated code can contain mistakes. The test suite and the review process
|
|
224
|
+
reduce that risk, but they do not remove it. If you rely on Tolkira in a
|
|
225
|
+
production pipeline, validate the report against your own results and pin the
|
|
226
|
+
version you use.
|
|
227
|
+
|
|
228
|
+
## License
|
|
229
|
+
|
|
230
|
+
MIT. See [`LICENSE`](https://github.com/Silasoa/tolkira/blob/main/LICENSE).
|
|
231
|
+
|
|
232
|
+
Tolkira is not affiliated with Cucumber, SmartBear, Seed-Test or any
|
|
233
|
+
test-framework vendor. Cucumber and Gherkin are used descriptively; the project
|
|
234
|
+
uses the MIT-licensed Cucumber Messages format and package.
|
package/SECURITY.md
ADDED
|
@@ -0,0 +1,30 @@
|
|
|
1
|
+
# Security Policy
|
|
2
|
+
|
|
3
|
+
## Supported versions
|
|
4
|
+
|
|
5
|
+
Tolkira is pre-1.0. Security fixes are applied to the latest released version.
|
|
6
|
+
|
|
7
|
+
## Reporting a vulnerability
|
|
8
|
+
|
|
9
|
+
Please do not open a public issue for a security problem. Use GitHub’s private
|
|
10
|
+
vulnerability reporting / Security Advisories for this repository, or contact
|
|
11
|
+
the maintainers privately.
|
|
12
|
+
|
|
13
|
+
Include:
|
|
14
|
+
|
|
15
|
+
- affected version or commit;
|
|
16
|
+
- a minimal reproduction;
|
|
17
|
+
- impact and suggested fix, if known.
|
|
18
|
+
|
|
19
|
+
## Scope
|
|
20
|
+
|
|
21
|
+
Tolkira processes untrusted test output. Security-relevant areas include:
|
|
22
|
+
|
|
23
|
+
- HTML/JS injection through test names, metadata, titles and attachment names;
|
|
24
|
+
- active HTML/SVG attachments;
|
|
25
|
+
- path handling for output and attachments;
|
|
26
|
+
- denial of service through very large reports or attachments;
|
|
27
|
+
- dependency vulnerabilities.
|
|
28
|
+
|
|
29
|
+
Tolkira does not send telemetry and does not make network requests. A report
|
|
30
|
+
should remain fully offline.
|