tolkira 0.0.0-stage → 0.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/DESIGN.md +178 -0
- package/GLOSSARY.md +60 -0
- package/LICENSE +21 -0
- package/README.md +186 -2
- package/SECURITY.md +30 -0
- package/dist/cli.d.ts +5 -0
- package/dist/cli.js +2812 -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 +2592 -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 +90 -0
- package/docs/CUCUMBER-COMPATIBILITY.md +102 -0
- package/docs/JUNIT-XML.md +74 -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,187 @@
|
|
|
1
|
-
#
|
|
1
|
+
# Tolkira
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
> **The interpreter for your test results.**
|
|
4
|
+
> Clear, embeddable HTML reports for Cucumber JSON, Messages, and beyond.
|
|
5
|
+
|
|
6
|
+
**Status: v0.1.0.** Messages and legacy Cucumber JSON render to one
|
|
7
|
+
self-contained HTML file with a simple report, an optional Details tab, the
|
|
8
|
+
CLI/API, title/metadata, screenshots, browser tests and a stable JSON summary
|
|
9
|
+
for agents.
|
|
10
|
+
|
|
11
|
+
## Install
|
|
12
|
+
|
|
13
|
+
```shell
|
|
14
|
+
npm install --global tolkira
|
|
15
|
+
tolkira test-results/ --out report.html --title "Daily run"
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
Or run it without a global install:
|
|
19
|
+
|
|
20
|
+
```shell
|
|
21
|
+
npx tolkira test-results/ --out report.html --title "Daily run"
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
## What is Tolkira?
|
|
25
|
+
|
|
26
|
+
Tolkira turns test results into a single, self-contained HTML report that works
|
|
27
|
+
offline and can be embedded anywhere. It starts with the two Cucumber formats
|
|
28
|
+
that matter today:
|
|
29
|
+
|
|
30
|
+
- **Legacy Cucumber JSON** — the format produced by cucumber-js, cucumber-jvm,
|
|
31
|
+
cucumber-ruby, Behave and many compatible tools.
|
|
32
|
+
- **Cucumber Messages (NDJSON)** — the modern, implementation-independent
|
|
33
|
+
format produced by Cucumber's official implementations.
|
|
34
|
+
|
|
35
|
+
The important part is that **screenshots and attachments survive**. A test
|
|
36
|
+
report without the failing screenshot is not a report; it is a table.
|
|
37
|
+
|
|
38
|
+
Tolkira is deliberately not tied to Cucumber or Gherkin in its name. The
|
|
39
|
+
adapter layer can grow to other result formats later without renaming the
|
|
40
|
+
product.
|
|
41
|
+
|
|
42
|
+
## Why the name?
|
|
43
|
+
|
|
44
|
+
Tolkira is a coined name from the Scandinavian word **“tolk”** — interpreter.
|
|
45
|
+
A test report is an interpreter: it translates raw test events into something
|
|
46
|
+
people can understand, and it bridges old JSON pipelines and modern Messages
|
|
47
|
+
without forcing a migration.
|
|
48
|
+
|
|
49
|
+
The name is pronounced approximately **TOL-kee-rah**.
|
|
50
|
+
|
|
51
|
+
## What works today
|
|
52
|
+
|
|
53
|
+
- **Inputs:** legacy Cucumber JSON (cucumber-js 2.3.1-13.3.0, Behave 1.3.3,
|
|
54
|
+
cucumber-jvm 7.22.1 and cucumber-ruby 12.0.1 tested), Cucumber
|
|
55
|
+
Messages (cucumber-js 11.2, cucumber-jvm 7.22.1 and cucumber-ruby 12.0.1
|
|
56
|
+
fixtures), and JUnit XML (basic mode: suites, test cases, failures, durations
|
|
57
|
+
and system output; no steps or screenshots). Multiple files and directories
|
|
58
|
+
merge into one run.
|
|
59
|
+
- **Output:** one self-contained HTML file; CSS, script and attachments are
|
|
60
|
+
inline. No CDN, no network requests, no telemetry.
|
|
61
|
+
- **Report:** failed-first simple report, feature/scenario disclosures, inline
|
|
62
|
+
screenshots and text attachments, doc strings, data tables, hooks, tags,
|
|
63
|
+
durations and errors; search and status filters; dark mode.
|
|
64
|
+
- **Details:** pass/fail counts, feature table, an environment block with
|
|
65
|
+
producer/runtime/OS/CPU/protocol, run metadata and the agent summary.
|
|
66
|
+
- **Branding:** title, metadata, logo and accent colour.
|
|
67
|
+
- **CLI/API:** `tolkira <input...> --out <file>`, `--json`,
|
|
68
|
+
`summarizeReport()`, atomic output, size limits, CSP and escaping.
|
|
69
|
+
- **Compatibility:** experimental
|
|
70
|
+
`tolkira/compat/cucumber-html-reporter` options shim.
|
|
71
|
+
- **Browsers:** Chromium, Firefox and WebKit tests.
|
|
72
|
+
|
|
73
|
+
## Release status
|
|
74
|
+
|
|
75
|
+
v0.1.0 is prepared and the gate is green: typecheck, lint, unit tests, build
|
|
76
|
+
and browser tests. Tag and npm publication wait for the npm account and
|
|
77
|
+
trusted publishing. Until the first publish, build from source (see
|
|
78
|
+
Development). Known gaps are listed in the changelog and
|
|
79
|
+
`docs/research/open-questions.md`.
|
|
80
|
+
|
|
81
|
+
## Non-goals for v0.1
|
|
82
|
+
|
|
83
|
+
- Rich per-framework adapters (Playwright JSON, Allure results, .NET TRX).
|
|
84
|
+
A basic JUnit XML mode is planned for cheap breadth.
|
|
85
|
+
- History, trends and flaky-test analytics (Allure/ReportPortal territory).
|
|
86
|
+
- PDF or email reports.
|
|
87
|
+
- Localisation (the shell starts in English; German can follow).
|
|
88
|
+
- A plugin system, SaaS, test management or a live server.
|
|
89
|
+
- A first-class visual clone of the old cucumber-html-reporter themes.
|
|
90
|
+
|
|
91
|
+
## Principles
|
|
92
|
+
|
|
93
|
+
- **One file, no network.** A report must be shareable as a CI artefact.
|
|
94
|
+
- **Few dependencies.** Prefer Node built-ins and the official Cucumber
|
|
95
|
+
Messages package over another framework.
|
|
96
|
+
- **The data pipeline is the product.** The report shell is ours; the input
|
|
97
|
+
model is the official Cucumber Messages format.
|
|
98
|
+
- **The report is a designed artifact.** Simple by default, deeper analysis on
|
|
99
|
+
demand.
|
|
100
|
+
- **Security at the trust boundary.** Test names, metadata and attachments are
|
|
101
|
+
untrusted input.
|
|
102
|
+
- **Spec first, tests first, small slices.**
|
|
103
|
+
- **MIT, no telemetry, no vendor lock-in.**
|
|
104
|
+
|
|
105
|
+
## Migration from cucumber-html-reporter
|
|
106
|
+
|
|
107
|
+
The legacy options object is accepted as-is; only the import changes.
|
|
108
|
+
|
|
109
|
+
```js
|
|
110
|
+
import { generate } from 'tolkira/compat/cucumber-html-reporter';
|
|
111
|
+
|
|
112
|
+
await generate({
|
|
113
|
+
jsonFile: 'reports/cucumber.json',
|
|
114
|
+
output: 'reports/report.html',
|
|
115
|
+
brandTitle: 'Checkout acceptance',
|
|
116
|
+
metadata: { Browser: 'Chrome', Environment: 'Staging' },
|
|
117
|
+
});
|
|
118
|
+
```
|
|
119
|
+
|
|
120
|
+
The shim is experimental. Themes, charts, external screenshots and browser
|
|
121
|
+
launch are not reproduced; they warn and use Tolkira's defaults. It consumes
|
|
122
|
+
the same input JSON, never the old HTML. See
|
|
123
|
+
[`docs/COMPATIBILITY.md`](docs/COMPATIBILITY.md).
|
|
124
|
+
|
|
125
|
+
## Documentation
|
|
126
|
+
|
|
127
|
+
- [`docs/PRODUCT.md`](https://github.com/Silasoa/tolkira/blob/main/docs/PRODUCT.md) — vision, audience, scope, market context.
|
|
128
|
+
- [`docs/ARCHITECTURE.md`](https://github.com/Silasoa/tolkira/blob/main/docs/ARCHITECTURE.md) — system shape and decisions.
|
|
129
|
+
- [`docs/AGENT-INTERFACE.md`](https://github.com/Silasoa/tolkira/blob/main/docs/AGENT-INTERFACE.md) — JSON schema and agent workflow.
|
|
130
|
+
- [`docs/COMPARISON.md`](https://github.com/Silasoa/tolkira/blob/main/docs/COMPARISON.md) — Seed-Test visual comparison and parity gaps.
|
|
131
|
+
- [`docs/COMPATIBILITY.md`](https://github.com/Silasoa/tolkira/blob/main/docs/COMPATIBILITY.md) — cucumber-html-reporter migration shim.
|
|
132
|
+
- [`docs/CUCUMBER-COMPATIBILITY.md`](https://github.com/Silasoa/tolkira/blob/main/docs/CUCUMBER-COMPATIBILITY.md) — tested Cucumber producers and versions.
|
|
133
|
+
- [`docs/JUNIT-XML.md`](https://github.com/Silasoa/tolkira/blob/main/docs/JUNIT-XML.md) — JUnit XML basic mode.
|
|
134
|
+
- [`docs/agents/review.md`](https://github.com/Silasoa/tolkira/blob/main/docs/agents/review.md) — review and audit protocol.
|
|
135
|
+
- [`GLOSSARY.md`](https://github.com/Silasoa/tolkira/blob/main/GLOSSARY.md) — shared language.
|
|
136
|
+
- [`AGENTS.md`](https://github.com/Silasoa/tolkira/blob/main/AGENTS.md) — how agents work in this repository.
|
|
137
|
+
- [`openspec/`](https://github.com/Silasoa/tolkira/tree/main/openspec) — the change contract and specifications.
|
|
138
|
+
|
|
139
|
+
## Development
|
|
140
|
+
|
|
141
|
+
Requires Node.js 22 or newer.
|
|
142
|
+
|
|
143
|
+
```shell
|
|
144
|
+
npm install
|
|
145
|
+
npx playwright install chromium firefox webkit
|
|
146
|
+
npm run check
|
|
147
|
+
npm run test:e2e
|
|
148
|
+
npm run stress -- 1000
|
|
149
|
+
```
|
|
150
|
+
|
|
151
|
+
Generate a report from one of the fixtures:
|
|
152
|
+
|
|
153
|
+
```shell
|
|
154
|
+
npm run build
|
|
155
|
+
node dist/cli.js test/fixtures/legacy/happy.json \
|
|
156
|
+
--out report.html \
|
|
157
|
+
--title "My report" \
|
|
158
|
+
--meta Browser=Chrome \
|
|
159
|
+
--accent "#1b5e20"
|
|
160
|
+
|
|
161
|
+
# Optional: embed a logo (path is yours, not part of the repo)
|
|
162
|
+
node dist/cli.js test-results/ --out report.html --logo path/to/logo.png
|
|
163
|
+
```
|
|
164
|
+
|
|
165
|
+
The check runs typecheck, lint, unit tests and build. The browser test renders
|
|
166
|
+
both a Messages report and a legacy JSON report, opens a screenshot, exercises
|
|
167
|
+
search, status filters, expand/collapse and checks that an HTML attachment does
|
|
168
|
+
not execute. `npm run stress -- 1000` checks a 1,000-scenario report; see
|
|
169
|
+
[`docs/COMPARISON.md`](docs/COMPARISON.md) for the Seed-Test comparison.
|
|
170
|
+
|
|
171
|
+
For agents and CI, print the stable summary instead of scraping HTML:
|
|
172
|
+
|
|
173
|
+
```shell
|
|
174
|
+
node dist/cli.js test-results/ --out report.html --json
|
|
175
|
+
node dist/cli.js test-results/ --json
|
|
176
|
+
```
|
|
177
|
+
|
|
178
|
+
See [`docs/AGENT-INTERFACE.md`](docs/AGENT-INTERFACE.md) for the schema and exit
|
|
179
|
+
codes.
|
|
180
|
+
|
|
181
|
+
## License
|
|
182
|
+
|
|
183
|
+
MIT. See [`LICENSE`](LICENSE).
|
|
184
|
+
|
|
185
|
+
Tolkira is not affiliated with Cucumber, SmartBear or any test-framework
|
|
186
|
+
vendor. Cucumber and Gherkin are used descriptively; the project uses the
|
|
187
|
+
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.
|