@testrelic/maestro-analytics 1.0.0-next.14 → 1.0.0-next.18

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.
Files changed (2) hide show
  1. package/README.md +152 -2
  2. package/package.json +2 -2
package/README.md CHANGED
@@ -32,18 +32,168 @@ maestro test --format junit --output report.xml --test-output-dir ./artifacts ./
32
32
  npx testrelic-maestro report --junit report.xml --artifacts ./artifacts
33
33
  ```
34
34
 
35
- ## Cloud Reporting
35
+ ## Local Reporter
36
36
 
37
- Set the `TESTRELIC_API_KEY` environment variable or add it to `.testrelic/testrelic-config.json`:
37
+ After every run the package writes two files to disk and (by default) opens the HTML report in your browser automatically — no API key or network connection required.
38
+
39
+ | Output | Default path |
40
+ |--------|-------------|
41
+ | JSON data file | `./test-results/testrelic-maestro.json` |
42
+ | Interactive HTML report | `./test-results/testrelic-maestro.html` |
43
+
44
+ ### Customizing via CLI flags
45
+
46
+ ```bash
47
+ # Change the output directory
48
+ npx testrelic-maestro test --output-dir ./my-reports ./flows
49
+
50
+ # Set an explicit HTML report path
51
+ npx testrelic-maestro test --html-report ./reports/results.html ./flows
52
+
53
+ # Don't open the browser automatically after the run
54
+ npx testrelic-maestro test --no-open ./flows
55
+
56
+ # Suppress console summary output
57
+ npx testrelic-maestro test --quiet ./flows
58
+
59
+ # Combine options
60
+ npx testrelic-maestro test --output-dir ./ci-reports --no-open --quiet ./flows
61
+ ```
62
+
63
+ The same flags work for the `report` subcommand:
64
+
65
+ ```bash
66
+ npx testrelic-maestro report \
67
+ --junit report.xml \
68
+ --artifacts ./artifacts \
69
+ --flows-dir ./flows \
70
+ --output-dir ./ci-reports \
71
+ --html-report ./ci-reports/maestro.html \
72
+ --no-open
73
+ ```
74
+
75
+ ### Customizing via the programmatic API
76
+
77
+ Use `resolveConfig` and `orchestrateReport` directly when you need fine-grained control from a Node.js script:
78
+
79
+ ```ts
80
+ import { resolveConfig, orchestrateReport } from '@testrelic/maestro-analytics';
81
+
82
+ const config = resolveConfig({
83
+ outputPath: './reports/testrelic-maestro.json',
84
+ htmlReportPath: './reports/maestro-report.html',
85
+ openReport: false,
86
+ includeScreenshots: true,
87
+ includeVideo: true,
88
+ includeAiAnalysis: true,
89
+ includeLogs: true,
90
+ includeFlowMetadata: true,
91
+ quiet: false,
92
+ metadata: { branch: 'main', buildId: process.env.BUILD_ID },
93
+ });
94
+
95
+ const result = await orchestrateReport({
96
+ junitPath: './report.xml',
97
+ testOutputDir: './artifacts',
98
+ flowsDir: './flows',
99
+ config,
100
+ });
101
+
102
+ console.log(`Passed: ${result.report.summary.passed}`);
103
+ console.log(`Failed: ${result.report.summary.failed}`);
104
+ console.log(`AI defects: ${result.aiDefects.length}`);
105
+ ```
106
+
107
+ ### Local reporter configuration reference
108
+
109
+ | Option | Type | Default | Description |
110
+ |--------|------|---------|-------------|
111
+ | `outputPath` | `string` | `./test-results/testrelic-maestro.json` | Path for the JSON data file |
112
+ | `htmlReportPath` | `string` | Derived from `outputPath` | Path for the interactive HTML report |
113
+ | `openReport` | `boolean` | `true` | Auto-open the HTML report in the browser after the run |
114
+ | `includeScreenshots` | `boolean` | `true` | Embed screenshots for each flow in the report |
115
+ | `includeVideo` | `boolean` | `true` | Embed video recordings for each flow |
116
+ | `includeAiAnalysis` | `boolean` | `true` | Include AI-detected UI defects in the report |
117
+ | `includeLogs` | `boolean` | `true` | Include Maestro debug logs |
118
+ | `includeFlowMetadata` | `boolean` | `true` | Parse YAML flow headers for `appId`, tags, and properties |
119
+ | `flowsDir` | `string` | — | Directory containing Maestro YAML flow files (enriches flow metadata) |
120
+ | `quiet` | `boolean` | `false` | Suppress the console summary printed after each run |
121
+ | `metadata` | `object` | — | Custom key/value pairs attached to the run (e.g. build ID, branch name) |
122
+ | `reportMode` | `'batch'` | `'batch'` | Upload strategy — `'batch'` sends all results at the end of the run |
123
+
124
+ ---
125
+
126
+ ## Cloud Integration
127
+
128
+ Upload results to the [TestRelic](https://testrelic.ai) dashboard in addition to the local report. Cloud upload is optional and requires an API key.
129
+
130
+ ### Option 1: Environment variable (recommended for CI)
131
+
132
+ ```bash
133
+ export TESTRELIC_API_KEY=trk_your_api_key_here
134
+ npx testrelic-maestro test ./flows
135
+ ```
136
+
137
+ ### Option 2: CLI flag
138
+
139
+ ```bash
140
+ npx testrelic-maestro test --api-key trk_your_api_key_here ./flows
141
+ ```
142
+
143
+ ### Option 3: Config file
144
+
145
+ Create `.testrelic/testrelic-config.json` in your project root:
38
146
 
39
147
  ```json
40
148
  {
41
149
  "cloud": {
42
150
  "apiKey": "${TESTRELIC_API_KEY}"
151
+ },
152
+ "testrelic-repo": {
153
+ "name": "my-mobile-app"
154
+ }
155
+ }
156
+ ```
157
+
158
+ The `apiKey` value can be a literal string or an environment variable reference in `${VAR_NAME}` form. The config file is discovered automatically by walking up the directory tree from the current working directory.
159
+
160
+ ### Full config file reference
161
+
162
+ ```json
163
+ {
164
+ "cloud": {
165
+ "apiKey": "${TESTRELIC_API_KEY}",
166
+ "endpoint": "https://platform.testrelic.ai/api/v1",
167
+ "upload": "batch"
168
+ },
169
+ "testrelic-repo": {
170
+ "name": "my-mobile-app"
171
+ },
172
+ "queue": {
173
+ "maxAge": "7d",
174
+ "directory": ".testrelic/queue"
43
175
  }
44
176
  }
45
177
  ```
46
178
 
179
+ | Field | Description |
180
+ |-------|-------------|
181
+ | `cloud.apiKey` | TestRelic API key. Supports `${ENV_VAR}` references. |
182
+ | `cloud.endpoint` | API endpoint (default: `https://platform.testrelic.ai/api/v1`) |
183
+ | `cloud.upload` | Upload strategy: `batch` (default), `realtime`, or `both` |
184
+ | `testrelic-repo.name` | Project name shown in the TestRelic dashboard |
185
+ | `queue.maxAge` | How long to retain queued uploads (e.g. `7d`, `24h`). Default: `7d` |
186
+ | `queue.directory` | Local directory for queued uploads (default: `.testrelic/queue`) |
187
+
188
+ ### Priority order
189
+
190
+ When the same setting is provided in multiple places, the following priority applies (highest wins):
191
+
192
+ 1. Environment variables (`TESTRELIC_API_KEY`, `TESTRELIC_CLOUD_ENDPOINT`)
193
+ 2. CLI flags (`--api-key`, `--endpoint`)
194
+ 3. `.testrelic/testrelic-config.json` config file
195
+ 4. Built-in defaults
196
+
47
197
  ## What Gets Captured
48
198
 
49
199
  | Data | Source |
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@testrelic/maestro-analytics",
3
- "version": "1.0.0-next.14",
3
+ "version": "1.0.0-next.18",
4
4
  "description": "Maestro mobile testing analytics — JUnit/artifact parsing, step-level timing, AI defect aggregation, visual regression tracking, and interactive HTML reports",
5
5
  "keywords": [
6
6
  "maestro",
@@ -55,7 +55,7 @@
55
55
  "dependencies": {
56
56
  "fast-xml-parser": "^4.5.0",
57
57
  "yaml": "^2.7.0",
58
- "@testrelic/core": "2.4.11-next.14"
58
+ "@testrelic/core": "2.4.11-next.18"
59
59
  },
60
60
  "devDependencies": {
61
61
  "@types/node": "^20.0.0",