tolkira 0.1.2 → 0.3.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 +12 -7
- package/GLOSSARY.md +108 -0
- package/README.md +222 -20
- package/SECURITY.md +3 -0
- package/dist/cli.js +1860 -555
- package/dist/cli.js.map +4 -4
- package/dist/compat/cucumber-html-reporter.cjs +12 -0
- package/dist/compat/cucumber-html-reporter.d.cts +10 -0
- package/dist/compat/cucumber-html-reporter.js +95 -24
- package/dist/compat/cucumber-html-reporter.js.map +4 -4
- package/dist/compat/options.d.ts +2 -0
- package/dist/index.d.ts +4 -7
- package/dist/index.js +1829 -549
- package/dist/index.js.map +4 -4
- package/dist/input/background.d.ts +4 -0
- package/dist/input/junit.d.ts +3 -1
- package/dist/input/load.d.ts +13 -0
- package/dist/options.d.ts +12 -0
- package/dist/output.d.ts +2 -0
- package/dist/render/ansi.d.ts +2 -0
- package/dist/render/client-bundle.d.ts +1 -0
- package/dist/render/escape.d.ts +1 -1
- package/dist/render/html.d.ts +1 -0
- package/dist/render/markdown.d.ts +1 -0
- package/dist/render/search.d.ts +18 -0
- package/dist/report/attachment.d.ts +10 -0
- package/dist/report/model.d.ts +87 -3
- package/dist/report/status.d.ts +12 -0
- package/dist/stream.d.ts +15 -0
- package/dist/summary.d.ts +15 -2
- package/dist/text.d.ts +15 -0
- package/docs/AGENT-INTERFACE.md +158 -21
- package/docs/COMPATIBILITY.md +59 -5
- package/docs/CUCUMBER-COMPATIBILITY.md +193 -0
- package/docs/JUNIT-XML.md +27 -2
- package/docs/LIMITATIONS.md +17 -0
- package/llms.txt +31 -0
- package/package.json +31 -8
|
@@ -0,0 +1,4 @@
|
|
|
1
|
+
import type { Background } from '@cucumber/messages';
|
|
2
|
+
/** Marks the Background node legacy normalisation invents for step resolution. */
|
|
3
|
+
export declare function markSyntheticBackground(background: Background): void;
|
|
4
|
+
export declare function isSyntheticBackground(background: Background): boolean;
|
package/dist/input/junit.d.ts
CHANGED
|
@@ -1,3 +1,5 @@
|
|
|
1
1
|
import type { Envelope } from '@cucumber/messages';
|
|
2
2
|
export declare function looksLikeJUnit(content: string): boolean;
|
|
3
|
-
export declare function parseJUnitXml(content: string, source: string
|
|
3
|
+
export declare function parseJUnitXml(content: string, source: string, options?: {
|
|
4
|
+
idPrefix?: string;
|
|
5
|
+
}): Promise<Envelope[]>;
|
package/dist/input/load.d.ts
CHANGED
|
@@ -1,2 +1,15 @@
|
|
|
1
1
|
import type { Envelope } from '@cucumber/messages';
|
|
2
|
+
export declare const MAX_TOTAL_INPUT_BYTES: number;
|
|
3
|
+
export declare function addInputBytes(totalBytes: number, size: number): number;
|
|
4
|
+
export interface LoadedInput {
|
|
5
|
+
file: string;
|
|
6
|
+
envelopes: Envelope[];
|
|
7
|
+
}
|
|
8
|
+
export declare function loadInputs(inputs: string | string[]): Promise<LoadedInput[]>;
|
|
2
9
|
export declare function loadEnvelopes(inputs: string | string[]): Promise<Envelope[]>;
|
|
10
|
+
/**
|
|
11
|
+
* Maps a feature URI to its input file name, but only when the URI belongs to
|
|
12
|
+
* exactly one file. Shared or missing provenance is omitted so the report can
|
|
13
|
+
* render a flat list instead of an invented group.
|
|
14
|
+
*/
|
|
15
|
+
export declare function provenanceFor(groups: LoadedInput[]): Map<string, string>;
|
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
export interface RenderReportOptions {
|
|
2
|
+
title?: string;
|
|
3
|
+
metadata?: Record<string, string>;
|
|
4
|
+
logo?: string;
|
|
5
|
+
accent?: string;
|
|
6
|
+
}
|
|
7
|
+
export declare function renderOptions(options: RenderReportOptions): {
|
|
8
|
+
title: string;
|
|
9
|
+
metadata: Record<string, string> | undefined;
|
|
10
|
+
logo: string | undefined;
|
|
11
|
+
accent: string | undefined;
|
|
12
|
+
};
|
package/dist/output.d.ts
CHANGED
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export declare const CLIENT_SCRIPT: string;
|
package/dist/render/escape.d.ts
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
export declare function escapeHtml(value:
|
|
1
|
+
export declare function escapeHtml(value: unknown): string;
|
package/dist/render/html.d.ts
CHANGED
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export declare function renderDescription(description: string): string;
|
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
export declare const SEARCH_OPEN_CAP = 20;
|
|
2
|
+
export declare function isTagExpression(query: string): boolean;
|
|
3
|
+
export type TagExpressionEvaluator = (tags: string[]) => boolean;
|
|
4
|
+
export declare function compileTagExpression(query: string): TagExpressionEvaluator | undefined;
|
|
5
|
+
export declare function evaluateTagExpression(query: string, tags: string[]): boolean | undefined;
|
|
6
|
+
export interface UrlState {
|
|
7
|
+
query: string;
|
|
8
|
+
hidden: string[];
|
|
9
|
+
tag: string;
|
|
10
|
+
}
|
|
11
|
+
export declare function parseUrlState(search: string, knownStatuses: readonly string[], knownTags: readonly string[]): UrlState;
|
|
12
|
+
export declare function serializeUrlState(current: string, state: UrlState): string;
|
|
13
|
+
export interface OpenRow {
|
|
14
|
+
visible: boolean;
|
|
15
|
+
open: boolean;
|
|
16
|
+
}
|
|
17
|
+
export declare function rowsToOpen(rows: readonly OpenRow[], cap?: number): number[];
|
|
18
|
+
export declare function rememberHiddenOpen(open: boolean, openedBySearch: boolean): boolean;
|
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
/** Text attachments above this size render as escaped text without parsing. */
|
|
2
|
+
export declare const MAX_TEXT_ATTACHMENT_BYTES = 262144;
|
|
3
|
+
export declare const MEDIA_EXTENSIONS: Record<string, string>;
|
|
4
|
+
export declare function normalizedMediaType(mediaType: string): string;
|
|
5
|
+
/**
|
|
6
|
+
* Normalises a declared media type and drops everything outside the report's
|
|
7
|
+
* renderer list. Unknown or forged types (XHTML, XML, comma-joined values)
|
|
8
|
+
* become application/octet-stream so they can never reach a data URI verbatim.
|
|
9
|
+
*/
|
|
10
|
+
export declare function safeMediaType(mediaType: string): string;
|
package/dist/report/model.d.ts
CHANGED
|
@@ -1,5 +1,6 @@
|
|
|
1
1
|
import type { Envelope } from '@cucumber/messages';
|
|
2
|
-
|
|
2
|
+
import { type ReportStatus } from './status.js';
|
|
3
|
+
export type { ReportStatus } from './status.js';
|
|
3
4
|
export interface ReportAttachment {
|
|
4
5
|
fileName: string;
|
|
5
6
|
mediaType: string;
|
|
@@ -10,6 +11,7 @@ export interface ReportAttachment {
|
|
|
10
11
|
}
|
|
11
12
|
export interface ReportStep {
|
|
12
13
|
id: string;
|
|
14
|
+
order: number;
|
|
13
15
|
keyword: string;
|
|
14
16
|
text: string;
|
|
15
17
|
status: ReportStatus;
|
|
@@ -17,8 +19,67 @@ export interface ReportStep {
|
|
|
17
19
|
message?: string;
|
|
18
20
|
docString?: string;
|
|
19
21
|
dataTable?: string[][];
|
|
22
|
+
suggestions?: Array<{
|
|
23
|
+
language?: string;
|
|
24
|
+
code: string;
|
|
25
|
+
}>;
|
|
26
|
+
definitions?: Array<{
|
|
27
|
+
pattern: string;
|
|
28
|
+
source?: string;
|
|
29
|
+
}>;
|
|
30
|
+
parameters?: Array<{
|
|
31
|
+
start: number;
|
|
32
|
+
value: string;
|
|
33
|
+
type: string;
|
|
34
|
+
}>;
|
|
20
35
|
attachments: ReportAttachment[];
|
|
21
|
-
|
|
36
|
+
}
|
|
37
|
+
export interface ReportHook {
|
|
38
|
+
id: string;
|
|
39
|
+
order: number;
|
|
40
|
+
type: string;
|
|
41
|
+
name?: string;
|
|
42
|
+
status: ReportStatus;
|
|
43
|
+
durationMs: number;
|
|
44
|
+
message?: string;
|
|
45
|
+
attachments: ReportAttachment[];
|
|
46
|
+
}
|
|
47
|
+
export interface ReportRunHook {
|
|
48
|
+
id: string;
|
|
49
|
+
type: string;
|
|
50
|
+
name?: string;
|
|
51
|
+
status: ReportStatus;
|
|
52
|
+
durationMs: number;
|
|
53
|
+
message?: string;
|
|
54
|
+
attachments: ReportAttachment[];
|
|
55
|
+
}
|
|
56
|
+
export interface ReportOutline {
|
|
57
|
+
id: string;
|
|
58
|
+
keyword: string;
|
|
59
|
+
name: string;
|
|
60
|
+
description: string;
|
|
61
|
+
tags: string[];
|
|
62
|
+
examplesId: string;
|
|
63
|
+
examplesKeyword: string;
|
|
64
|
+
examplesName: string;
|
|
65
|
+
examplesDescription: string;
|
|
66
|
+
examplesTags: string[];
|
|
67
|
+
examplesIndex: number;
|
|
68
|
+
exampleIndex: number;
|
|
69
|
+
}
|
|
70
|
+
export interface ReportBackground {
|
|
71
|
+
id: string;
|
|
72
|
+
keyword: string;
|
|
73
|
+
name: string;
|
|
74
|
+
description: string;
|
|
75
|
+
}
|
|
76
|
+
export interface ReportRule {
|
|
77
|
+
id: string;
|
|
78
|
+
keyword: string;
|
|
79
|
+
name: string;
|
|
80
|
+
description: string;
|
|
81
|
+
tags: string[];
|
|
82
|
+
backgrounds: ReportBackground[];
|
|
22
83
|
}
|
|
23
84
|
export interface ReportScenario {
|
|
24
85
|
id: string;
|
|
@@ -28,12 +89,20 @@ export interface ReportScenario {
|
|
|
28
89
|
uri: string;
|
|
29
90
|
featureName: string;
|
|
30
91
|
ruleName?: string;
|
|
92
|
+
rule?: ReportRule;
|
|
31
93
|
status: ReportStatus;
|
|
94
|
+
/** True when the selected test case reported at least one raw result. */
|
|
95
|
+
executed: boolean;
|
|
32
96
|
durationMs: number;
|
|
33
97
|
attempt: number;
|
|
34
98
|
startedAt?: string;
|
|
99
|
+
/** Scenario tags from the AST; examples-block tags for outline rows. */
|
|
100
|
+
ownTags: string[];
|
|
101
|
+
/** Inherited pickle tags, kept for filtering and search. */
|
|
35
102
|
tags: string[];
|
|
103
|
+
outline?: ReportOutline;
|
|
36
104
|
steps: ReportStep[];
|
|
105
|
+
hooks: ReportHook[];
|
|
37
106
|
attachments: ReportAttachment[];
|
|
38
107
|
extraAttachments: ReportAttachment[];
|
|
39
108
|
}
|
|
@@ -44,10 +113,12 @@ export interface ReportFeature {
|
|
|
44
113
|
uri: string;
|
|
45
114
|
description: string;
|
|
46
115
|
tags: string[];
|
|
116
|
+
backgrounds: ReportBackground[];
|
|
47
117
|
status: ReportStatus;
|
|
48
118
|
durationMs: number;
|
|
49
119
|
scenarios: ReportScenario[];
|
|
50
120
|
attachments: number;
|
|
121
|
+
sourceFile?: string;
|
|
51
122
|
}
|
|
52
123
|
export interface ReportCounts {
|
|
53
124
|
features: number;
|
|
@@ -57,15 +128,27 @@ export interface ReportCounts {
|
|
|
57
128
|
steps: Record<ReportStatus, number> & {
|
|
58
129
|
total: number;
|
|
59
130
|
};
|
|
131
|
+
hooks: Record<ReportStatus, number> & {
|
|
132
|
+
total: number;
|
|
133
|
+
};
|
|
60
134
|
attachments: number;
|
|
61
135
|
attachmentBytes: number;
|
|
62
136
|
}
|
|
137
|
+
export interface ReportCi {
|
|
138
|
+
name?: string;
|
|
139
|
+
url?: string;
|
|
140
|
+
remote?: string;
|
|
141
|
+
revision?: string;
|
|
142
|
+
branch?: string;
|
|
143
|
+
tag?: string;
|
|
144
|
+
}
|
|
63
145
|
export interface ReportEnvironment {
|
|
64
146
|
producer?: string;
|
|
65
147
|
runtime?: string;
|
|
66
148
|
os?: string;
|
|
67
149
|
cpu?: string;
|
|
68
150
|
protocol?: string;
|
|
151
|
+
ci?: ReportCi;
|
|
69
152
|
}
|
|
70
153
|
export interface ReportModel {
|
|
71
154
|
features: ReportFeature[];
|
|
@@ -76,6 +159,7 @@ export interface ReportModel {
|
|
|
76
159
|
source: string;
|
|
77
160
|
environment?: ReportEnvironment;
|
|
78
161
|
scenarios: ReportScenario[];
|
|
162
|
+
runHooks: ReportRunHook[];
|
|
79
163
|
runAttachments: ReportAttachment[];
|
|
80
164
|
}
|
|
81
|
-
export declare function buildReportModel(envelopes: Envelope[]): ReportModel;
|
|
165
|
+
export declare function buildReportModel(envelopes: Envelope[], provenance?: Map<string, string>): ReportModel;
|
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
export type ReportStatus = 'passed' | 'failed' | 'skipped' | 'pending' | 'undefined' | 'ambiguous' | 'unknown';
|
|
2
|
+
/** Raw Cucumber ordinal; the report comparator forces passed last. */
|
|
3
|
+
export declare function statusSeverity(status: ReportStatus): number;
|
|
4
|
+
export interface ExecutedStatus {
|
|
5
|
+
executed: boolean;
|
|
6
|
+
status: ReportStatus;
|
|
7
|
+
}
|
|
8
|
+
/**
|
|
9
|
+
* Worst status across executed rows only: passed when every executed row
|
|
10
|
+
* passed, unknown when nothing executed. Unexecuted rows never contribute.
|
|
11
|
+
*/
|
|
12
|
+
export declare function worstExecutedStatus(scenarios: readonly ExecutedStatus[]): ReportStatus;
|
package/dist/stream.d.ts
ADDED
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
import { Transform, type TransformCallback } from 'node:stream';
|
|
2
|
+
import type { Envelope } from '@cucumber/messages';
|
|
3
|
+
import { type RenderReportOptions } from './options.js';
|
|
4
|
+
/**
|
|
5
|
+
* A `CucumberHtmlStream`-shaped adapter for Cucumber Messages. It collects
|
|
6
|
+
* envelopes and renders one HTML document on flush with the same options and
|
|
7
|
+
* renderer as `renderReport`.
|
|
8
|
+
*/
|
|
9
|
+
export declare class CucumberHtmlStream extends Transform {
|
|
10
|
+
private readonly options;
|
|
11
|
+
private readonly envelopes;
|
|
12
|
+
constructor(options?: RenderReportOptions);
|
|
13
|
+
_transform(envelope: Envelope, _encoding: BufferEncoding, callback: TransformCallback): void;
|
|
14
|
+
_flush(callback: TransformCallback): void;
|
|
15
|
+
}
|
package/dist/summary.d.ts
CHANGED
|
@@ -1,6 +1,7 @@
|
|
|
1
1
|
import type { Envelope } from '@cucumber/messages';
|
|
2
|
-
|
|
3
|
-
export
|
|
2
|
+
import { type ReportStatus } from './report/status.js';
|
|
3
|
+
export declare const SUMMARY_SCHEMA_VERSION = 2;
|
|
4
|
+
export type SummaryStatus = ReportStatus;
|
|
4
5
|
export interface StatusCounts {
|
|
5
6
|
total: number;
|
|
6
7
|
passed: number;
|
|
@@ -14,15 +15,26 @@ export interface StatusCounts {
|
|
|
14
15
|
export interface SummaryStep {
|
|
15
16
|
keyword: string;
|
|
16
17
|
text: string;
|
|
18
|
+
name?: string;
|
|
17
19
|
status: SummaryStatus;
|
|
18
20
|
durationMs: number;
|
|
19
21
|
message?: string;
|
|
22
|
+
suggestions?: Array<{
|
|
23
|
+
language?: string;
|
|
24
|
+
code: string;
|
|
25
|
+
}>;
|
|
26
|
+
definitions?: Array<{
|
|
27
|
+
pattern: string;
|
|
28
|
+
source?: string;
|
|
29
|
+
}>;
|
|
20
30
|
}
|
|
21
31
|
export interface SummaryScenario {
|
|
22
32
|
name: string;
|
|
23
33
|
uri: string;
|
|
24
34
|
feature: string;
|
|
25
35
|
status: SummaryStatus;
|
|
36
|
+
/** True when the selected test case reported at least one raw result. */
|
|
37
|
+
executed: boolean;
|
|
26
38
|
durationMs: number;
|
|
27
39
|
attempt: number;
|
|
28
40
|
tags: string[];
|
|
@@ -44,6 +56,7 @@ export interface ReportSummary {
|
|
|
44
56
|
};
|
|
45
57
|
scenarios: SummaryScenario[];
|
|
46
58
|
}
|
|
59
|
+
export declare function displayUri(uri: string): string;
|
|
47
60
|
/**
|
|
48
61
|
* Builds a stable, renderer-independent summary from Cucumber Messages.
|
|
49
62
|
* This is the machine-readable contract for agents and CI tools.
|
package/dist/text.d.ts
ADDED
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
export declare function stripBidiControls(value: string): string;
|
|
2
|
+
export interface EscapeScan {
|
|
3
|
+
/** Index just past the escape sequence. */
|
|
4
|
+
end: number;
|
|
5
|
+
/** SGR parameters when the sequence is a Select Graphic Rendition. */
|
|
6
|
+
sgr?: string;
|
|
7
|
+
}
|
|
8
|
+
export declare function isEscapeIntroducer(code: number): boolean;
|
|
9
|
+
export declare function scanEscape(text: string, start: number): EscapeScan;
|
|
10
|
+
/**
|
|
11
|
+
* Removes ANSI escape sequences, including 8-bit C1 escapes, and other terminal
|
|
12
|
+
* controls. Newlines and tabs are kept so copied and summarised text stays
|
|
13
|
+
* readable.
|
|
14
|
+
*/
|
|
15
|
+
export declare function stripAnsi(text: string): string;
|
package/docs/AGENT-INTERFACE.md
CHANGED
|
@@ -68,11 +68,37 @@ The CLI validates logo bytes and rejects unsupported types or a size over
|
|
|
68
68
|
2 MB. The API only accepts a `data:image/...;base64,...` logo; anything else is
|
|
69
69
|
omitted.
|
|
70
70
|
|
|
71
|
-
|
|
71
|
+
### Messages stream
|
|
72
|
+
|
|
73
|
+
`CucumberHtmlStream` is a shape-compatible Node `Transform` for callers that
|
|
74
|
+
already hold Cucumber Messages envelopes:
|
|
75
|
+
|
|
76
|
+
```ts
|
|
77
|
+
import { Readable } from 'node:stream';
|
|
78
|
+
import { CucumberHtmlStream } from 'tolkira';
|
|
79
|
+
|
|
80
|
+
const html = await new Promise<string>((resolve, reject) => {
|
|
81
|
+
let output = '';
|
|
82
|
+
Readable.from(envelopes)
|
|
83
|
+
.pipe(new CucumberHtmlStream({ title: 'Nightly' }))
|
|
84
|
+
.on('data', (chunk) => (output += chunk))
|
|
85
|
+
.on('error', reject)
|
|
86
|
+
.on('end', () => resolve(output));
|
|
87
|
+
});
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
The stream accepts `Envelope` objects in object mode, buffers the run and
|
|
91
|
+
renders one HTML document on flush. It takes `RenderReportOptions` (title,
|
|
92
|
+
metadata, logo, accent) and produces the same HTML for the same envelopes and
|
|
93
|
+
options. It is not an incremental renderer. It writes no files and emits no
|
|
94
|
+
summary; use `summarizeReport` or `generateReport` when you also need the
|
|
95
|
+
stable JSON. The whole run is held in memory, exactly like the file API.
|
|
96
|
+
|
|
97
|
+
## Summary schema, version 2
|
|
72
98
|
|
|
73
99
|
```json
|
|
74
100
|
{
|
|
75
|
-
"schemaVersion":
|
|
101
|
+
"schemaVersion": 2,
|
|
76
102
|
"status": "failed",
|
|
77
103
|
"durationMs": 12.4,
|
|
78
104
|
"counts": {
|
|
@@ -108,6 +134,7 @@ omitted.
|
|
|
108
134
|
"uri": "features/screenshot.feature",
|
|
109
135
|
"feature": "Screenshot attachment",
|
|
110
136
|
"status": "failed",
|
|
137
|
+
"executed": true,
|
|
111
138
|
"durationMs": 10,
|
|
112
139
|
"attempt": 0,
|
|
113
140
|
"tags": ["@failing"],
|
|
@@ -129,35 +156,131 @@ omitted.
|
|
|
129
156
|
This example is abridged: it shows only the failing scenario, not the passing
|
|
130
157
|
one that carries the screenshot. The totals reflect the whole input.
|
|
131
158
|
|
|
159
|
+
Undefined and ambiguous Messages steps add optional diagnostic fields:
|
|
160
|
+
|
|
161
|
+
```json
|
|
162
|
+
{
|
|
163
|
+
"keyword": "Given",
|
|
164
|
+
"text": "a list of 8 things",
|
|
165
|
+
"status": "undefined",
|
|
166
|
+
"durationMs": 0,
|
|
167
|
+
"suggestions": [
|
|
168
|
+
{
|
|
169
|
+
"language": "typescript",
|
|
170
|
+
"code": "Given(\"a list of {int} things\", (int: number) => {\n return \"pending\"\n})"
|
|
171
|
+
},
|
|
172
|
+
{
|
|
173
|
+
"language": "typescript",
|
|
174
|
+
"code": "Given(\"a list of {float} things\", (float: number) => {\n return \"pending\"\n})"
|
|
175
|
+
}
|
|
176
|
+
]
|
|
177
|
+
}
|
|
178
|
+
```
|
|
179
|
+
|
|
180
|
+
```json
|
|
181
|
+
{
|
|
182
|
+
"keyword": "Given",
|
|
183
|
+
"text": "a step with multiple definitions",
|
|
184
|
+
"status": "ambiguous",
|
|
185
|
+
"durationMs": 0,
|
|
186
|
+
"definitions": [
|
|
187
|
+
{
|
|
188
|
+
"pattern": "^a (.*?) with (.*?)$",
|
|
189
|
+
"source": "samples/ambiguous/ambiguous.ts:3"
|
|
190
|
+
},
|
|
191
|
+
{
|
|
192
|
+
"pattern": "^a step with (.*?)$",
|
|
193
|
+
"source": "samples/ambiguous/ambiguous.ts:7"
|
|
194
|
+
}
|
|
195
|
+
]
|
|
196
|
+
}
|
|
197
|
+
```
|
|
198
|
+
|
|
132
199
|
Field contract:
|
|
133
200
|
|
|
134
|
-
- `schemaVersion` is `
|
|
201
|
+
- `schemaVersion` is `2`. A breaking change increments it.
|
|
135
202
|
- `status` is one of `passed`, `failed`, `skipped`, `pending`, `undefined`,
|
|
136
203
|
`ambiguous`, `unknown`.
|
|
137
|
-
- `status` is the worst scenario status
|
|
138
|
-
using the standard Cucumber
|
|
139
|
-
|
|
140
|
-
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
204
|
+
- `status` is the worst executed scenario status, or `failed` when a test-run
|
|
205
|
+
hook fails. A scenario is the worst step status, using the standard Cucumber
|
|
206
|
+
severity order. When nothing executed, the run status is `unknown` unless a
|
|
207
|
+
test-run hook failed.
|
|
208
|
+
- `counts.features` is the number of features with at least one scenario row,
|
|
209
|
+
executed or unexecuted, matching the HTML feature list. A document whose
|
|
210
|
+
pickles never started contributes no row and is not counted.
|
|
211
|
+
- `counts.scenarios` counts executed scenarios only, so `total` can be smaller
|
|
212
|
+
than `scenarios.length`. `counts.scenarios` and `counts.steps` always contain
|
|
213
|
+
every status key, even when the value is `0`. `total` is the sum.
|
|
214
|
+
- `scenarios[].executed` is `true` when the selected test case reported at
|
|
215
|
+
least one raw step result, including a hook result. An unexecuted scenario
|
|
216
|
+
keeps `status: "unknown"` and `executed: false`; it is not counted in
|
|
217
|
+
`counts.scenarios`. A pickle that never started has no entry at all.
|
|
218
|
+
- `durationMs` is a number of milliseconds and includes scenario and test-run
|
|
219
|
+
hook time. `steps[].durationMs` is rounded to three decimals.
|
|
144
220
|
- `scenarios` is sorted by `uri`, then `name`, so output is stable across runs.
|
|
145
|
-
- `
|
|
221
|
+
- `scenarios[].name` is the Cucumber pickle name. Examples of one scenario
|
|
222
|
+
outline can share the same name; the HTML report labels rows with `#1.1` and
|
|
223
|
+
shows the examples block name on the examples heading and in triage and
|
|
224
|
+
copy-failure text, but the summary does not expose them yet.
|
|
225
|
+
- `scenarios[].tags` is the inherited pickle tag set, including feature, rule,
|
|
226
|
+
scenario and examples tags. The HTML report uses the same set for its tag
|
|
227
|
+
filter and search. Feature and rule tags render once at their section;
|
|
228
|
+
scenario tags render on the scenario row or, for an outline, on the outline
|
|
229
|
+
heading, and examples tags on the examples heading. Example rows repeat
|
|
230
|
+
neither scenario nor examples tags. The summary does not expose rules,
|
|
231
|
+
backgrounds or the own/inherited distinction.
|
|
232
|
+
- `attempt` is the latest started Cucumber attempt for that scenario, even when
|
|
233
|
+
that attempt reported no result. An earlier retried attempt is ignored.
|
|
146
234
|
- `attachments.bytes` is the decoded size, not the base64 length.
|
|
147
235
|
- `steps[].message` is present only when the step result has a message. For
|
|
148
|
-
hooks, `keyword` is `"Hook"
|
|
236
|
+
hooks, `keyword` is `"Hook"`, `text` is the hook type and `name` is present
|
|
237
|
+
when Cucumber provides one. Summary step counts include hook entries; the
|
|
238
|
+
HTML report counts steps and hooks separately. A failed test-run hook makes
|
|
239
|
+
the overall summary `status` failed.
|
|
240
|
+
- `steps[].suggestions` is present only for an undefined Messages step with
|
|
241
|
+
`suggestion` envelopes. Each entry has an optional `language` and the `code`
|
|
242
|
+
to implement. `steps[].definitions` is present only for an ambiguous Messages
|
|
243
|
+
step with `stepDefinition` envelopes. Each entry has the `pattern` and an
|
|
244
|
+
optional `source` in `uri:line` form with absolute paths reduced to a
|
|
245
|
+
relative form. Both fields are additive, so `schemaVersion` stays 2;
|
|
246
|
+
a passed step never carries them.
|
|
149
247
|
- Attachment file names are not part of the summary. `scenarios[].attachments`
|
|
150
|
-
is a count; open the HTML report to see
|
|
248
|
+
is a count and is 0 for an unexecuted scenario; open the HTML report to see
|
|
249
|
+
the image or file. Unnamed attachments use a deterministic
|
|
250
|
+
`attachment.<ext>` fallback in HTML; unknown media types normalise to
|
|
251
|
+
`application/octet-stream` and `attachment.bin`.
|
|
252
|
+
- CI metadata from Messages `meta.ci` is HTML-only. It renders in the report
|
|
253
|
+
header and Details, but no CI field appears in the summary and
|
|
254
|
+
`schemaVersion` stays 2. When `ci.name` is missing, the http(s) `ci.url` is
|
|
255
|
+
the link text. In a mixed input the first non-empty CI block wins, and
|
|
256
|
+
meta synthesized by the legacy adapter cannot erase it. Legacy JSON and
|
|
257
|
+
JUnit never invent CI metadata; use the `metadata` option for a legacy path.
|
|
258
|
+
|
|
259
|
+
## Migrating to schema version 2
|
|
260
|
+
|
|
261
|
+
Version 2 adds `executed` to every scenario and changes scenario counts to
|
|
262
|
+
cover executed scenarios only:
|
|
263
|
+
|
|
264
|
+
- `counts.scenarios.total` can be smaller than `scenarios.length`; use the
|
|
265
|
+
counts for aggregate decisions.
|
|
266
|
+
- An unexecuted scenario has `status: "unknown"` and `executed: false`. That
|
|
267
|
+
`unknown` is not a failure signal.
|
|
268
|
+
- Filter on `executed` (or use `counts.scenarios`) before treating a
|
|
269
|
+
scenario's `status` as an outcome. A legacy Cucumber JSON scenario with no
|
|
270
|
+
steps and no hooks is now unexecuted, so its scenario total drops by one
|
|
271
|
+
compared with version 1.
|
|
272
|
+
- Never-started pickles remain absent from `scenarios` and the counts.
|
|
151
273
|
|
|
152
274
|
The summary does not expose absolute input paths: absolute `uri` values are
|
|
153
|
-
reduced to a
|
|
275
|
+
reduced to a relative form (`features/...`, or the last path segments for files
|
|
276
|
+
outside `features/`).
|
|
154
277
|
|
|
155
278
|
## Recommended agent workflow
|
|
156
279
|
|
|
157
280
|
1. Run the tests and keep the raw Cucumber JSON or Messages.
|
|
158
281
|
2. Run `tolkira <inputs> --out report.html --json`.
|
|
159
|
-
3. Parse stdout once.
|
|
160
|
-
for diagnosis.
|
|
282
|
+
3. Parse stdout once. Filter on `executed` (or use `counts`) and use `status`,
|
|
283
|
+
counts and `scenarios[].steps[].message` for diagnosis.
|
|
161
284
|
4. If you need screenshots or the full Gherkin view, open `report.html`; do not
|
|
162
285
|
scrape it for pass/fail data.
|
|
163
286
|
5. Attach or upload the HTML report as the human-facing artifact.
|
|
@@ -166,14 +289,28 @@ reduced to a report-relative form (`features/...`).
|
|
|
166
289
|
|
|
167
290
|
- Remote attachments (`attachment.url`, `externalAttachment`) are rejected on
|
|
168
291
|
purpose; the report must work offline. Inline the bytes.
|
|
169
|
-
- Markdown
|
|
292
|
+
- Description Markdown renders only in the HTML report. Remote image
|
|
293
|
+
destinations are neutralised and images render as alt text, so the report
|
|
294
|
+
loads no external asset. JUnit `description` attributes are a best-effort,
|
|
295
|
+
non-standard mapping; they never appear in the summary.
|
|
296
|
+
- Tag-expression search, the tag dropdown and `?query=`/`?hide=`/`?tag=` URL
|
|
297
|
+
state are HTML-only progressive enhancements. The summary schema, counts and
|
|
298
|
+
no-JS report are unchanged.
|
|
170
299
|
- Inputs are capped at 100 MB in total; attachments at 50 MB each and 100 MB
|
|
171
300
|
total.
|
|
172
301
|
- The HTML report includes a hash-based CSP and never executes attachments.
|
|
173
|
-
- History, trends, retries beyond the latest attempt and
|
|
174
|
-
|
|
302
|
+
- History, trends, retries beyond the latest attempt and a native Playwright
|
|
303
|
+
adapter are not supported. JUnit XML is a basic input mode; see
|
|
304
|
+
[`LIMITATIONS.md`](LIMITATIONS.md).
|
|
175
305
|
- Legacy Cucumber JSON outlines arrive as expanded scenarios; the original
|
|
176
306
|
outline `examples` table is not reconstructed. Behave-shaped durations are
|
|
177
307
|
interpreted as nanoseconds, like cucumber-js.
|
|
178
|
-
-
|
|
179
|
-
|
|
308
|
+
- Rules and backgrounds are an HTML presentation feature. The version-2 summary
|
|
309
|
+
keeps the flat scenario list; `scenarios[].tags` remains the inherited tag
|
|
310
|
+
set. Legacy JSON and JUnit never invent rule or background structure.
|
|
311
|
+
- Legacy Cucumber JSON and JUnit have no suggestion or step-definition
|
|
312
|
+
envelopes. An undefined or ambiguous legacy step still shows the status lead
|
|
313
|
+
in HTML, but never invented snippets or definitions; JUnit renders no
|
|
314
|
+
diagnostics.
|
|
315
|
+
- cucumber-js, Behave-shaped, cucumber-jvm, cucumber-ruby and Messages inputs
|
|
316
|
+
are covered by fixtures.
|