tolkira 0.1.0 → 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/README.md CHANGED
@@ -1,112 +1,132 @@
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.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).
10
17
 
11
18
  ## Install
12
19
 
13
20
  ```shell
14
21
  npm install --global tolkira
15
- tolkira test-results/ --out report.html --title "Daily run"
22
+ tolkira --help
16
23
  ```
17
24
 
18
25
  Or run it without a global install:
19
26
 
20
27
  ```shell
21
- npx tolkira test-results/ --out report.html --title "Daily run"
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
22
49
  ```
23
50
 
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.
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.
108
124
 
109
125
  ```js
126
+ // before
127
+ const reporter = require('cucumber-html-reporter');
128
+
129
+ // after
110
130
  import { generate } from 'tolkira/compat/cucumber-html-reporter';
111
131
 
112
132
  await generate({
@@ -119,26 +139,38 @@ await generate({
119
139
 
120
140
  The shim is experimental. Themes, charts, external screenshots and browser
121
141
  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).
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.
124
157
 
125
158
  ## Documentation
126
159
 
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.
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.
138
170
 
139
171
  ## Development
140
172
 
141
- Requires Node.js 22 or newer.
173
+ Tolkira requires Node.js 22 or newer.
142
174
 
143
175
  ```shell
144
176
  npm install
@@ -148,40 +180,55 @@ npm run test:e2e
148
180
  npm run stress -- 1000
149
181
  ```
150
182
 
151
- Generate a report from one of the fixtures:
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`:
152
189
 
153
190
  ```shell
154
191
  npm run build
155
192
  node dist/cli.js test/fixtures/legacy/happy.json \
156
193
  --out report.html \
157
194
  --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
195
+ --meta Browser=Chrome
163
196
  ```
164
197
 
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.
198
+ ## Contributing and feedback
170
199
 
171
- For agents and CI, print the stable summary instead of scraping HTML:
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.
172
204
 
173
- ```shell
174
- node dist/cli.js test-results/ --out report.html --json
175
- node dist/cli.js test-results/ --json
176
- ```
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.
177
222
 
178
- See [`docs/AGENT-INTERFACE.md`](docs/AGENT-INTERFACE.md) for the schema and exit
179
- codes.
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.
180
227
 
181
228
  ## License
182
229
 
183
- MIT. See [`LICENSE`](LICENSE).
230
+ MIT. See [`LICENSE`](https://github.com/Silasoa/tolkira/blob/main/LICENSE).
184
231
 
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.
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.