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 +179 -128
- package/dist/cli.js +317 -22
- package/dist/cli.js.map +3 -3
- package/dist/index.d.ts +1 -1
- package/dist/index.js +305 -19
- package/dist/index.js.map +3 -3
- package/docs/COMPATIBILITY.md +11 -3
- package/docs/JUNIT-XML.md +3 -0
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,112 +1,133 @@
|
|
|
1
1
|
# Tolkira
|
|
2
2
|
|
|
3
|
-
|
|
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
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
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
|
|
23
|
+
tolkira --help
|
|
16
24
|
```
|
|
17
25
|
|
|
18
26
|
Or run it without a global install:
|
|
19
27
|
|
|
20
28
|
```shell
|
|
21
|
-
npx tolkira
|
|
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
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
- **
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
-
|
|
84
|
-
|
|
85
|
-
-
|
|
86
|
-
-
|
|
87
|
-
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
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/
|
|
128
|
-
|
|
129
|
-
- [`docs/
|
|
130
|
-
|
|
131
|
-
- [`docs/
|
|
132
|
-
|
|
133
|
-
- [`docs/
|
|
134
|
-
-
|
|
135
|
-
- [`
|
|
136
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
174
|
-
|
|
175
|
-
|
|
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
|
-
|
|
179
|
-
|
|
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
|
|
186
|
-
|
|
187
|
-
|
|
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.
|