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 +175 -128
- package/dist/cli.js +304 -19
- package/dist/cli.js.map +3 -3
- package/dist/index.d.ts +1 -1
- package/dist/index.js +304 -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,132 @@
|
|
|
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.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
|
|
22
|
+
tolkira --help
|
|
16
23
|
```
|
|
17
24
|
|
|
18
25
|
Or run it without a global install:
|
|
19
26
|
|
|
20
27
|
```shell
|
|
21
|
-
npx tolkira
|
|
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
|
-
|
|
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.
|
|
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/
|
|
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.
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
174
|
-
|
|
175
|
-
|
|
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
|
-
|
|
179
|
-
|
|
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
|
|
186
|
-
vendor. Cucumber and Gherkin are used descriptively; the project
|
|
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.
|