@testrelic/maestro-analytics 1.1.0 → 1.2.0-next.54

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import { TestStatus, CloudReporterOptions, ReportMode, CloudConfig, TimelineEntry, Summary, TestRunReport, AuthMode, GitMetadata, TimelineStep, CIMetadata } from '@testrelic/core';
+import { TestStatus, CloudReporterOptions, ReportMode, CloudConfig, ApiCallRecord, TimelineEntry, Summary, TestRunReport, AuthMode, GitMetadata, TimelineStep, CIMetadata } from '@testrelic/core';
 export { ActionCategory, ActionStep, ArtifactRunManifest, AuthMode, AuthState, CIMetadata, CIProvider, CloudConfig, CloudReporterOptions, ConsoleLogEntry, ConsoleLogLevel, FailureDiagnostic, GitMetadata, MergeOptions, QueueEntry, ReportMode, StreamingReportSummary, Summary, TestArtifacts, TestDetailData, TestIndexEntry, TestResult, TestRunReport, TestStatus, TimelineEntry, TimelineStep, UploadStrategy } from '@testrelic/core';
 export { mergeReports, mergeReportsFromDirectory } from './merge.cjs';
 
@@ -11,6 +11,55 @@ export { mergeReports, mergeReportsFromDirectory } from './merge.cjs';
  */
 
 type MaestroPlatform = 'android' | 'ios' | 'web' | 'unknown';
+/**
+ * Network capture configuration. See `network-proxy.ts` and `parsers/har-parser.ts`.
+ *
+ * Maestro is a black-box UI driver — it can't intercept HTTP from inside the
+ * mobile app the way Playwright can. Two strategies are supported:
+ *
+ *  - `mitmproxy` (auto-spawn): SDK launches `mitmdump` with a bundled addon
+ *    that writes redacted ApiCallRecord JSONL. Requires `mitmdump` on PATH
+ *    and a configured proxy / CA on the device.
+ *  - `har` (user-supplied): User produces a HAR file with their own proxy
+ *    (Charles, Proxyman, mitmweb, etc.) and points the SDK at it.
+ */
+interface NetworkCaptureConfig {
+    /** When true, attempt to spawn mitmproxy and inject proxy settings into the device. Default: false. */
+    readonly enabled?: boolean;
+    /** Proxy listen port. Default: 8080. */
+    readonly proxyPort?: number;
+    /** Proxy listen host. Default: 127.0.0.1. */
+    readonly proxyHost?: string;
+    /** Path to a pre-generated HAR file to import instead of spawning a proxy. */
+    readonly harPath?: string;
+    /** Override the directory where mitmproxy writes its JSONL output. Default: `<outputDir>/network`. */
+    readonly outputDir?: string;
+    /** Skip auto-installing the mitmproxy CA on the device. Useful when the user pre-installed it. */
+    readonly skipCertInstall?: boolean;
+    /** Only capture calls whose URL matches one of these patterns (string substring or RegExp). */
+    readonly includeUrls?: (string | RegExp)[];
+    /** Exclude calls matching these patterns. Takes precedence over `includeUrls`. */
+    readonly excludeUrls?: (string | RegExp)[];
+    /** Header names whose values are replaced with "[REDACTED]". Case-insensitive. */
+    readonly redactHeaders?: string[];
+    /** Body field names whose values are replaced with "[REDACTED]" at any JSON depth. */
+    readonly redactBodyFields?: string[];
+    /** Maximum body size to capture (bytes). Larger bodies are truncated. Default: 1 MiB. */
+    readonly maxBodyBytes?: number;
+}
+interface ResolvedNetworkCaptureConfig {
+    readonly enabled: boolean;
+    readonly proxyPort: number;
+    readonly proxyHost: string;
+    readonly harPath: string | null;
+    readonly outputDir: string | null;
+    readonly skipCertInstall: boolean;
+    readonly includeUrls: readonly (string | RegExp)[];
+    readonly excludeUrls: readonly (string | RegExp)[];
+    readonly redactHeaders: readonly string[];
+    readonly redactBodyFields: readonly string[];
+    readonly maxBodyBytes: number;
+}
 interface MaestroReporterConfig {
     readonly outputPath?: string;
     readonly htmlReportPath?: string;
@@ -26,6 +75,7 @@ interface MaestroReporterConfig {
     readonly cloud?: CloudReporterOptions;
     readonly reportMode?: ReportMode;
     readonly quiet?: boolean;
+    readonly network?: NetworkCaptureConfig;
 }
 interface ResolvedMaestroConfig {
     readonly outputPath: string;
@@ -42,6 +92,7 @@ interface ResolvedMaestroConfig {
     readonly cloud: CloudConfig | null;
     readonly reportMode: ReportMode;
     readonly quiet: boolean;
+    readonly network: ResolvedNetworkCaptureConfig;
 }
 interface JUnitProperty {
     readonly name: string;
@@ -87,7 +138,35 @@ interface MaestroCommandStep {
     readonly timestamp: string;
     readonly selector?: string;
     readonly error?: string;
+    /**
+     * Raw passthrough of Maestro's metadata block (status / timestamp / duration / sequenceNumber).
+     * Kept separate from `details` because consumers like report-orchestrator depend on
+     * specific Maestro-internal keys (e.g. `metadata.path` for `startRecording`).
+     */
     readonly metadata?: Record<string, unknown>;
+    /**
+     * Extracted human-relevant command parameters surfaced in the timeline.
+     * Examples:
+     *   inputText  → { text: "<typed value>" }
+     *   swipe      → { direction: "UP", start: "0,0", end: "0,500", duration: 300 }
+     *   setLocation → { latitude: 37.7749, longitude: -122.4194 }
+     *   pressKey   → { key: "BACK" }
+     *   assertWithAI → { assertion: "<prompt>" }
+     *   runScript  → { path: "scripts/foo.js" } or { script: "<truncated source>" }
+     *
+     * Values are post-redaction (see api-redactor / details-redactor).
+     */
+    readonly details?: Record<string, unknown>;
+    /**
+     * Sort tiebreaker when two commands share a timestamp (Maestro emits sub-ms timing
+     * for fast back-to-back commands). Source: Maestro's metadata.sequenceNumber.
+     */
+    readonly sequenceNumber?: number;
+    /**
+     * Sub-commands when this step wraps a flow-control block (`retry`, `repeat`, `runFlow`).
+     * Empty / undefined for leaf commands.
+     */
+    readonly children?: MaestroCommandStep[];
 }
 interface MaestroFlowMetadata {
     readonly appId: string | null;
@@ -169,6 +248,7 @@ interface MaestroTestOptions {
     readonly env?: Record<string, string>;
     readonly quiet?: boolean;
     readonly maestroArgs?: string[];
+    readonly network?: NetworkCaptureConfig;
 }
 interface MaestroReportOptions {
     readonly junitPath?: string;
@@ -229,8 +309,16 @@ declare function discoverFlowFiles(dir: string): string[];
  * Also detects device/platform metadata from log content.
  */
 
-declare function parseLogContent(content: string): MaestroLogEntry[];
-declare function parseLogFile(filePath: string): MaestroLogEntry[];
+/**
+ * @param defaultDate Either an ISO date string (`YYYY-MM-DD`) or a Date object.
+ *   Used to anchor log lines that only carry a wall-clock time (`HH:MM:SS`).
+ *   Callers should pass the log file's mtime as a Date so the local-zone
+ *   conversion produces a correct UTC ISO timestamp for log entries. When a
+ *   plain string is passed, the timestamp is constructed without TZ-shift
+ *   compensation (legacy behaviour — may be off by the local UTC offset).
+ */
+declare function parseLogContent(content: string, defaultDate?: string | Date): MaestroLogEntry[];
+declare function parseLogFile(filePath: string, defaultDate?: string | Date): MaestroLogEntry[];
 declare function detectPlatformFromLogs(entries: MaestroLogEntry[]): MaestroPlatform;
 declare function discoverLogFiles(dir: string): string[];
 
@@ -261,8 +349,13 @@ declare function getArtifactStats(artifacts: CollectedArtifacts): Record<string,
  * Maps Maestro data to the @testrelic/core TimelineEntry shape.
  */
 
-declare function buildTimelineEntry(flow: MaestroFlowResult): TimelineEntry;
-declare function buildTimeline(flows: MaestroFlowResult[]): TimelineEntry[];
+/**
+ * Build a TimelineEntry for a single flow. Optionally accepts an
+ * `apiCallsByFlow` map keyed by `testId` (`${flowFile}::${flowName}`) so the
+ * orchestrator can plumb network capture results in without re-shaping flows.
+ */
+declare function buildTimelineEntry(flow: MaestroFlowResult, apiCallsByFlow?: ReadonlyMap<string, readonly ApiCallRecord[]>): TimelineEntry;
+declare function buildTimeline(flows: MaestroFlowResult[], apiCallsByFlow?: ReadonlyMap<string, readonly ApiCallRecord[]>): TimelineEntry[];
 
 /**
  * Computes Summary stats from TimelineEntry arrays.
@@ -311,9 +404,15 @@ interface MaestroRunResult {
     readonly debugOutputDir: string;
     readonly stdout: string;
     readonly stderr: string;
+    /** Directory where the network proxy wrote JSONL records (null when capture was disabled or failed to start). */
+    readonly networkJsonlDir: string | null;
 }
 declare function buildMaestroArgs(options: MaestroTestOptions, tempDir: string): string[];
-declare function runMaestro(options: MaestroTestOptions): Promise<MaestroRunResult>;
+interface RunMaestroExtras {
+    /** Optional network-capture config. When `enabled`, mitmproxy is spawned and the device is configured to route through it. */
+    readonly network?: ResolvedNetworkCaptureConfig;
+}
+declare function runMaestro(options: MaestroTestOptions, extras?: RunMaestroExtras): Promise<MaestroRunResult>;
 
 /**
  * Report orchestrator — ties all parsers together to produce
@@ -335,6 +434,12 @@ interface OrchestratorInput {
      * rely on heuristic detection that may return 'unknown'.
      */
     readonly platform?: MaestroPlatform;
+    /**
+     * Directory containing JSONL files emitted by `network-proxy.ts` (mitmproxy
+     * addon). When omitted, the orchestrator still picks up `config.network.harPath`
+     * if set. Unrelated to Maestro's own debug output.
+     */
+    readonly networkJsonlDir?: string | null;
 }
 interface OrchestratorResult {
     readonly report: TestRunReport;
@@ -419,6 +524,13 @@ interface TestResultForUpload {
         readonly timestamp: string;
         readonly source?: string | null;
     }>;
+    /**
+     * Per-flow captured API calls. The cloud platform's `normalizeApiCall` (in
+     * `server/src/utils/artifact-normalizer.ts`) accepts this shape directly and
+     * stores it as `network.json`. Surfaced in the Test Detail Network panel and
+     * via Ask AI's `query_network_logs` tool — works for free, no cloud changes.
+     */
+    readonly apiCalls?: readonly ApiCallRecord[];
 }
 interface RunUploadPayload {
     readonly runId: string;

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { TestStatus, CloudReporterOptions, ReportMode, CloudConfig, TimelineEntry, Summary, TestRunReport, AuthMode, GitMetadata, TimelineStep, CIMetadata } from '@testrelic/core';
+import { TestStatus, CloudReporterOptions, ReportMode, CloudConfig, ApiCallRecord, TimelineEntry, Summary, TestRunReport, AuthMode, GitMetadata, TimelineStep, CIMetadata } from '@testrelic/core';
 export { ActionCategory, ActionStep, ArtifactRunManifest, AuthMode, AuthState, CIMetadata, CIProvider, CloudConfig, CloudReporterOptions, ConsoleLogEntry, ConsoleLogLevel, FailureDiagnostic, GitMetadata, MergeOptions, QueueEntry, ReportMode, StreamingReportSummary, Summary, TestArtifacts, TestDetailData, TestIndexEntry, TestResult, TestRunReport, TestStatus, TimelineEntry, TimelineStep, UploadStrategy } from '@testrelic/core';
 export { mergeReports, mergeReportsFromDirectory } from './merge.js';
 
@@ -11,6 +11,55 @@ export { mergeReports, mergeReportsFromDirectory } from './merge.js';
  */
 
 type MaestroPlatform = 'android' | 'ios' | 'web' | 'unknown';
+/**
+ * Network capture configuration. See `network-proxy.ts` and `parsers/har-parser.ts`.
+ *
+ * Maestro is a black-box UI driver — it can't intercept HTTP from inside the
+ * mobile app the way Playwright can. Two strategies are supported:
+ *
+ *  - `mitmproxy` (auto-spawn): SDK launches `mitmdump` with a bundled addon
+ *    that writes redacted ApiCallRecord JSONL. Requires `mitmdump` on PATH
+ *    and a configured proxy / CA on the device.
+ *  - `har` (user-supplied): User produces a HAR file with their own proxy
+ *    (Charles, Proxyman, mitmweb, etc.) and points the SDK at it.
+ */
+interface NetworkCaptureConfig {
+    /** When true, attempt to spawn mitmproxy and inject proxy settings into the device. Default: false. */
+    readonly enabled?: boolean;
+    /** Proxy listen port. Default: 8080. */
+    readonly proxyPort?: number;
+    /** Proxy listen host. Default: 127.0.0.1. */
+    readonly proxyHost?: string;
+    /** Path to a pre-generated HAR file to import instead of spawning a proxy. */
+    readonly harPath?: string;
+    /** Override the directory where mitmproxy writes its JSONL output. Default: `<outputDir>/network`. */
+    readonly outputDir?: string;
+    /** Skip auto-installing the mitmproxy CA on the device. Useful when the user pre-installed it. */
+    readonly skipCertInstall?: boolean;
+    /** Only capture calls whose URL matches one of these patterns (string substring or RegExp). */
+    readonly includeUrls?: (string | RegExp)[];
+    /** Exclude calls matching these patterns. Takes precedence over `includeUrls`. */
+    readonly excludeUrls?: (string | RegExp)[];
+    /** Header names whose values are replaced with "[REDACTED]". Case-insensitive. */
+    readonly redactHeaders?: string[];
+    /** Body field names whose values are replaced with "[REDACTED]" at any JSON depth. */
+    readonly redactBodyFields?: string[];
+    /** Maximum body size to capture (bytes). Larger bodies are truncated. Default: 1 MiB. */
+    readonly maxBodyBytes?: number;
+}
+interface ResolvedNetworkCaptureConfig {
+    readonly enabled: boolean;
+    readonly proxyPort: number;
+    readonly proxyHost: string;
+    readonly harPath: string | null;
+    readonly outputDir: string | null;
+    readonly skipCertInstall: boolean;
+    readonly includeUrls: readonly (string | RegExp)[];
+    readonly excludeUrls: readonly (string | RegExp)[];
+    readonly redactHeaders: readonly string[];
+    readonly redactBodyFields: readonly string[];
+    readonly maxBodyBytes: number;
+}
 interface MaestroReporterConfig {
     readonly outputPath?: string;
     readonly htmlReportPath?: string;
@@ -26,6 +75,7 @@ interface MaestroReporterConfig {
     readonly cloud?: CloudReporterOptions;
     readonly reportMode?: ReportMode;
     readonly quiet?: boolean;
+    readonly network?: NetworkCaptureConfig;
 }
 interface ResolvedMaestroConfig {
     readonly outputPath: string;
@@ -42,6 +92,7 @@ interface ResolvedMaestroConfig {
     readonly cloud: CloudConfig | null;
     readonly reportMode: ReportMode;
     readonly quiet: boolean;
+    readonly network: ResolvedNetworkCaptureConfig;
 }
 interface JUnitProperty {
     readonly name: string;
@@ -87,7 +138,35 @@ interface MaestroCommandStep {
     readonly timestamp: string;
     readonly selector?: string;
     readonly error?: string;
+    /**
+     * Raw passthrough of Maestro's metadata block (status / timestamp / duration / sequenceNumber).
+     * Kept separate from `details` because consumers like report-orchestrator depend on
+     * specific Maestro-internal keys (e.g. `metadata.path` for `startRecording`).
+     */
     readonly metadata?: Record<string, unknown>;
+    /**
+     * Extracted human-relevant command parameters surfaced in the timeline.
+     * Examples:
+     *   inputText  → { text: "<typed value>" }
+     *   swipe      → { direction: "UP", start: "0,0", end: "0,500", duration: 300 }
+     *   setLocation → { latitude: 37.7749, longitude: -122.4194 }
+     *   pressKey   → { key: "BACK" }
+     *   assertWithAI → { assertion: "<prompt>" }
+     *   runScript  → { path: "scripts/foo.js" } or { script: "<truncated source>" }
+     *
+     * Values are post-redaction (see api-redactor / details-redactor).
+     */
+    readonly details?: Record<string, unknown>;
+    /**
+     * Sort tiebreaker when two commands share a timestamp (Maestro emits sub-ms timing
+     * for fast back-to-back commands). Source: Maestro's metadata.sequenceNumber.
+     */
+    readonly sequenceNumber?: number;
+    /**
+     * Sub-commands when this step wraps a flow-control block (`retry`, `repeat`, `runFlow`).
+     * Empty / undefined for leaf commands.
+     */
+    readonly children?: MaestroCommandStep[];
 }
 interface MaestroFlowMetadata {
     readonly appId: string | null;
@@ -169,6 +248,7 @@ interface MaestroTestOptions {
     readonly env?: Record<string, string>;
     readonly quiet?: boolean;
     readonly maestroArgs?: string[];
+    readonly network?: NetworkCaptureConfig;
 }
 interface MaestroReportOptions {
     readonly junitPath?: string;
@@ -229,8 +309,16 @@ declare function discoverFlowFiles(dir: string): string[];
  * Also detects device/platform metadata from log content.
  */
 
-declare function parseLogContent(content: string): MaestroLogEntry[];
-declare function parseLogFile(filePath: string): MaestroLogEntry[];
+/**
+ * @param defaultDate Either an ISO date string (`YYYY-MM-DD`) or a Date object.
+ *   Used to anchor log lines that only carry a wall-clock time (`HH:MM:SS`).
+ *   Callers should pass the log file's mtime as a Date so the local-zone
+ *   conversion produces a correct UTC ISO timestamp for log entries. When a
+ *   plain string is passed, the timestamp is constructed without TZ-shift
+ *   compensation (legacy behaviour — may be off by the local UTC offset).
+ */
+declare function parseLogContent(content: string, defaultDate?: string | Date): MaestroLogEntry[];
+declare function parseLogFile(filePath: string, defaultDate?: string | Date): MaestroLogEntry[];
 declare function detectPlatformFromLogs(entries: MaestroLogEntry[]): MaestroPlatform;
 declare function discoverLogFiles(dir: string): string[];
 
@@ -261,8 +349,13 @@ declare function getArtifactStats(artifacts: CollectedArtifacts): Record<string,
  * Maps Maestro data to the @testrelic/core TimelineEntry shape.
  */
 
-declare function buildTimelineEntry(flow: MaestroFlowResult): TimelineEntry;
-declare function buildTimeline(flows: MaestroFlowResult[]): TimelineEntry[];
+/**
+ * Build a TimelineEntry for a single flow. Optionally accepts an
+ * `apiCallsByFlow` map keyed by `testId` (`${flowFile}::${flowName}`) so the
+ * orchestrator can plumb network capture results in without re-shaping flows.
+ */
+declare function buildTimelineEntry(flow: MaestroFlowResult, apiCallsByFlow?: ReadonlyMap<string, readonly ApiCallRecord[]>): TimelineEntry;
+declare function buildTimeline(flows: MaestroFlowResult[], apiCallsByFlow?: ReadonlyMap<string, readonly ApiCallRecord[]>): TimelineEntry[];
 
 /**
  * Computes Summary stats from TimelineEntry arrays.
@@ -311,9 +404,15 @@ interface MaestroRunResult {
     readonly debugOutputDir: string;
     readonly stdout: string;
     readonly stderr: string;
+    /** Directory where the network proxy wrote JSONL records (null when capture was disabled or failed to start). */
+    readonly networkJsonlDir: string | null;
 }
 declare function buildMaestroArgs(options: MaestroTestOptions, tempDir: string): string[];
-declare function runMaestro(options: MaestroTestOptions): Promise<MaestroRunResult>;
+interface RunMaestroExtras {
+    /** Optional network-capture config. When `enabled`, mitmproxy is spawned and the device is configured to route through it. */
+    readonly network?: ResolvedNetworkCaptureConfig;
+}
+declare function runMaestro(options: MaestroTestOptions, extras?: RunMaestroExtras): Promise<MaestroRunResult>;
 
 /**
  * Report orchestrator — ties all parsers together to produce
@@ -335,6 +434,12 @@ interface OrchestratorInput {
      * rely on heuristic detection that may return 'unknown'.
      */
     readonly platform?: MaestroPlatform;
+    /**
+     * Directory containing JSONL files emitted by `network-proxy.ts` (mitmproxy
+     * addon). When omitted, the orchestrator still picks up `config.network.harPath`
+     * if set. Unrelated to Maestro's own debug output.
+     */
+    readonly networkJsonlDir?: string | null;
 }
 interface OrchestratorResult {
     readonly report: TestRunReport;
@@ -419,6 +524,13 @@ interface TestResultForUpload {
         readonly timestamp: string;
         readonly source?: string | null;
     }>;
+    /**
+     * Per-flow captured API calls. The cloud platform's `normalizeApiCall` (in
+     * `server/src/utils/artifact-normalizer.ts`) accepts this shape directly and
+     * stores it as `network.json`. Surfaced in the Test Detail Network panel and
+     * via Ask AI's `query_network_logs` tool — works for free, no cloud changes.
+     */
+    readonly apiCalls?: readonly ApiCallRecord[];
 }
 interface RunUploadPayload {
     readonly runId: string;