tolkira 0.1.0 → 0.1.2

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/README.md CHANGED
@@ -1,112 +1,133 @@
1
1
  # Tolkira
2
2
 
3
- > **The interpreter for your test results.**
4
- > Clear, embeddable HTML reports for Cucumber JSON, Messages, and beyond.
3
+ **One self-contained HTML report for Cucumber JSON, Messages and JUnit XML.**
5
4
 
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.
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.2** · [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 and approves releases. Most code,
13
+ > tests and documentation are drafted with large language models, then checked
14
+ > by automated tests and AI-assisted review passes. The maintainer reviews the
15
+ > release gate and tests the report from time to time. AI output can be wrong;
16
+ > please check the report against your own results and open an issue if
17
+ > something looks off. [Read more](#how-this-project-is-built).
10
18
 
11
19
  ## Install
12
20
 
13
21
  ```shell
14
22
  npm install --global tolkira
15
- tolkira test-results/ --out report.html --title "Daily run"
23
+ tolkira --help
16
24
  ```
17
25
 
18
26
  Or run it without a global install:
19
27
 
20
28
  ```shell
21
- npx tolkira test-results/ --out report.html --title "Daily run"
29
+ npx tolkira --help
30
+ ```
31
+
32
+ On Windows, `npx` can fail when the current folder contains parentheses in its
33
+ path. Use the global install or a folder without parentheses if that happens.
34
+
35
+ ## Quick start
36
+
37
+ ```shell
38
+ # One file, one report
39
+ tolkira test-results/ --out report.html --title "Checkout acceptance"
40
+
41
+ # Add your own metadata and brand colour
42
+ tolkira test-results/ --out report.html \
43
+ --title "Checkout acceptance" \
44
+ --meta "App version=0.3.2" \
45
+ --meta "Environment=Staging" \
46
+ --accent "#1b5e20"
47
+
48
+ # Embed a logo (PNG, JPEG, GIF, WebP or SVG)
49
+ tolkira test-results/ --out report.html --logo path/to/logo.png
22
50
  ```
23
51
 
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.
52
+ Tolkira accepts one or more files and directories. A directory is scanned
53
+ recursively for supported result files. Everything is merged into one report.
54
+
55
+ For CI tools and AI agents, ask for the stable JSON summary instead of scraping
56
+ the HTML:
57
+
58
+ ```shell
59
+ tolkira test-results/ --out report.html --json
60
+ tolkira test-results/ --json
61
+ ```
62
+
63
+ ## What you get
64
+
65
+ - **One file that works offline.** CSS, JavaScript and attachments are inline.
66
+ No network requests, no remote fonts, no analytics.
67
+ - **The failure first.** Failed scenarios are open by default, with the error
68
+ and screenshot where you need them.
69
+ - **Screenshots and attachments that survive.** Images, text, video, audio and
70
+ files are preserved through the legacy JSON adapter.
71
+ - **Search and filters.** Search scenarios, features, steps and tags; filter by
72
+ status and tag; open matching features automatically and highlight matches.
73
+ - **Copy failure.** Copy a failed scenario's feature, failed step and error as
74
+ plain text for a ticket or an agent.
75
+ - **A Details view when you need it.** Status distribution, a feature table,
76
+ run metadata and the Cucumber environment (producer, runtime, OS, CPU,
77
+ protocol).
78
+ - **A stable summary for agents.** `--json` and `summarizeReport()` return a
79
+ versioned schema with counts, durations, scenarios, steps and failure
80
+ messages.
81
+ - **Accessible by default.** Keyboard navigation, visible focus, text status
82
+ labels as well as colour, dark mode and 200% zoom reflow. Accessibility is an
83
+ ongoing effort; feedback is welcome.
84
+ - **Your branding.** Title, metadata, logo and accent colour without forking the
85
+ shell.
86
+
87
+ ## Supported inputs
88
+
89
+ | Input | What works |
90
+ | --- | --- |
91
+ | **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. |
92
+ | **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. |
93
+ | **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. |
94
+
95
+ Multiple files and mixed formats can be merged into one run. See
96
+ [`docs/CUCUMBER-COMPATIBILITY.md`](https://github.com/Silasoa/tolkira/blob/main/docs/CUCUMBER-COMPATIBILITY.md) for the
97
+ tested producer matrix and
98
+ [`docs/JUNIT-XML.md`](https://github.com/Silasoa/tolkira/blob/main/docs/JUNIT-XML.md) for the JUnit limits.
99
+
100
+ ## Why Tolkira exists
101
+
102
+ [`cucumber-html-reporter`](https://github.com/protractor-cucumber-framework/cucumber-html-reporter)
103
+ has been effectively unmaintained since October 2024. It still has a large
104
+ user base, but it loads Bootstrap, jQuery and Google Charts from CDNs, only
105
+ reads legacy JSON, and carries old runtime dependencies. Reports that should
106
+ work offline lose their layout and charts.
107
+
108
+ Tolkira keeps the old input working and fixes the parts that hurt:
109
+
110
+ - one offline file instead of CDN dependencies;
111
+ - legacy JSON **and** modern Messages;
112
+ - JUnit XML as cheap breadth for non-Cucumber teams;
113
+ - screenshots and attachments that stay in the report;
114
+ - a stable JSON summary for agents and CI;
115
+ - a small, reviewed dependency surface.
116
+
117
+ The visual comparison uses the report setup from
118
+ [Seed-Test](https://github.com/adessoSE/Seed-Test). If you are curious about
119
+ Seed-Test, you are welcome to take a look; the comparison notes and screenshots
120
+ are in [`docs/COMPARISON.md`](https://github.com/Silasoa/tolkira/blob/main/docs/COMPARISON.md).
121
+
122
+ ## Migrating from cucumber-html-reporter
123
+
124
+ The old options object is accepted as-is; only the import changes.
108
125
 
109
126
  ```js
127
+ // before
128
+ const reporter = require('cucumber-html-reporter');
129
+
130
+ // after
110
131
  import { generate } from 'tolkira/compat/cucumber-html-reporter';
111
132
 
112
133
  await generate({
@@ -119,26 +140,38 @@ await generate({
119
140
 
120
141
  The shim is experimental. Themes, charts, external screenshots and browser
121
142
  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).
143
+ the same input JSON, never the old rendered HTML. See
144
+ [`docs/COMPATIBILITY.md`](https://github.com/Silasoa/tolkira/blob/main/docs/COMPATIBILITY.md) for the full mapping and
145
+ caveats.
146
+
147
+ ## Privacy and limits
148
+
149
+ - No network requests, no telemetry, no remote fonts and no CDN.
150
+ - A restrictive Content Security Policy is embedded in every report.
151
+ - Test names, metadata and attachments are treated as untrusted input.
152
+ - Default limits: 100 MB total input, 50 MB per attachment and 100 MB total
153
+ attachments. A warning appears when a report grows beyond 10 MB.
154
+ - JUnit XML is intentionally basic; it is not a replacement for a native
155
+ Playwright, Jest or Allure report.
156
+ - One report is one file. External attachments for very large media are a
157
+ future option.
124
158
 
125
159
  ## Documentation
126
160
 
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.
161
+ - [`docs/AGENT-INTERFACE.md`](https://github.com/Silasoa/tolkira/blob/main/docs/AGENT-INTERFACE.md) — JSON schema, CLI
162
+ contract and exit codes.
163
+ - [`docs/CUCUMBER-COMPATIBILITY.md`](https://github.com/Silasoa/tolkira/blob/main/docs/CUCUMBER-COMPATIBILITY.md) — tested
164
+ Cucumber producers and versions.
165
+ - [`docs/JUNIT-XML.md`](https://github.com/Silasoa/tolkira/blob/main/docs/JUNIT-XML.md) — JUnit basic-mode mapping and
166
+ limits.
167
+ - [`docs/COMPATIBILITY.md`](https://github.com/Silasoa/tolkira/blob/main/docs/COMPATIBILITY.md) — migration from
168
+ cucumber-html-reporter.
169
+ - [`docs/COMPARISON.md`](https://github.com/Silasoa/tolkira/blob/main/docs/COMPARISON.md) — Seed-Test comparison and
170
+ remaining parity gaps.
138
171
 
139
172
  ## Development
140
173
 
141
- Requires Node.js 22 or newer.
174
+ Tolkira requires Node.js 22 or newer.
142
175
 
143
176
  ```shell
144
177
  npm install
@@ -148,40 +181,58 @@ npm run test:e2e
148
181
  npm run stress -- 1000
149
182
  ```
150
183
 
151
- Generate a report from one of the fixtures:
184
+ `npm run check` runs typecheck, lint, unit tests, build and the CSS generation
185
+ step. `npm run test:e2e` runs the browser tests in Chromium, Firefox and
186
+ WebKit. `npm run stress -- 1000` builds a 1,000-scenario report and reports size
187
+ and timing.
188
+
189
+ Build once and run the CLI from `dist`:
152
190
 
153
191
  ```shell
154
192
  npm run build
155
193
  node dist/cli.js test/fixtures/legacy/happy.json \
156
194
  --out report.html \
157
195
  --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
196
+ --meta Browser=Chrome
163
197
  ```
164
198
 
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.
199
+ ## Contributing and feedback
170
200
 
171
- For agents and CI, print the stable summary instead of scraping HTML:
201
+ Bug reports, accessibility feedback and compatibility fixtures are welcome.
202
+ If a producer or report shape does not work, a small sanitized fixture is the
203
+ most useful thing you can attach. Please do not include secrets or private test
204
+ data.
172
205
 
173
- ```shell
174
- node dist/cli.js test-results/ --out report.html --json
175
- node dist/cli.js test-results/ --json
176
- ```
206
+ If you want to work on the code, start with [`AGENTS.md`](https://github.com/Silasoa/tolkira/blob/main/AGENTS.md), the
207
+ [`openspec/`](https://github.com/Silasoa/tolkira/tree/main/openspec) change contracts and
208
+ [`docs/agents/review.md`](https://github.com/Silasoa/tolkira/blob/main/docs/agents/review.md). Product and architecture
209
+ notes live in [`docs/PRODUCT.md`](https://github.com/Silasoa/tolkira/blob/main/docs/PRODUCT.md) and
210
+ [`docs/ARCHITECTURE.md`](https://github.com/Silasoa/tolkira/blob/main/docs/ARCHITECTURE.md).
211
+
212
+ ## How this project is built
213
+
214
+ Tolkira is an experiment in AI-assisted open source. The maintainer defines the
215
+ problem, the scope and the design direction; large language models draft most of
216
+ the code, tests and documentation; automated tests and AI-assisted review passes
217
+ check changes; the maintainer reviews the release gate, approves versions and
218
+ tests the report from time to time.
219
+
220
+ The project does not name specific models in its files on purpose. The
221
+ maintainer configures the models and tooling. This keeps the project
222
+ model-agnostic and avoids turning a temporary tool choice into a permanent
223
+ dependency.
177
224
 
178
- See [`docs/AGENT-INTERFACE.md`](docs/AGENT-INTERFACE.md) for the schema and exit
179
- codes.
225
+ AI-generated code can contain mistakes. The test suite and the review process
226
+ reduce that risk, but they do not remove it. If you rely on Tolkira in a
227
+ production pipeline, validate the report against your own results and pin the
228
+ version you use.
180
229
 
181
230
  ## License
182
231
 
183
- MIT. See [`LICENSE`](LICENSE).
232
+ MIT. See [`LICENSE`](https://github.com/Silasoa/tolkira/blob/main/LICENSE).
184
233
 
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.
234
+ Tolkira is an independent project, not an official Cucumber, SmartBear or
235
+ Seed-Test product. The maintainer also contributes to Seed-Test; the visual
236
+ comparison uses Seed-Test's report setup. Cucumber and Gherkin are used
237
+ descriptively; the project uses the MIT-licensed Cucumber Messages format and
238
+ package.