@testrelic/maestro-analytics 1.2.0 → 1.2.1-next.56

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import { TestStatus, CloudReporterOptions, ReportMode, CloudConfig, ApiCallRecord, TimelineEntry, Summary, TestRunReport, AuthMode, GitMetadata, TimelineStep, CIMetadata } from '@testrelic/core';
+import { TestStatus, CloudReporterOptions, ReportMode, CloudConfig, ApiCallRecord, TimelineEntry, Summary, TestRunReport, TimelineStep, ActionStep, GitMetadata, CIMetadata, AuthMode } 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';
 
@@ -309,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[];
 
@@ -406,78 +414,6 @@ interface RunMaestroExtras {
 }
 declare function runMaestro(options: MaestroTestOptions, extras?: RunMaestroExtras): Promise<MaestroRunResult>;
 
-/**
- * Report orchestrator — ties all parsers together to produce
- * a TestRunReport from Maestro's output artifacts.
- */
-
-interface OrchestratorInput {
-    readonly junitPath?: string;
-    readonly testOutputDir?: string;
-    readonly debugOutputDir?: string;
-    readonly flowsDir?: string;
-    readonly config: ResolvedMaestroConfig;
-    /** Device serial / name used during this run, e.g. "emulator-5554". Passed through to each flow result and uploaded as deviceName. */
-    readonly device?: string;
-    /**
-     * Explicit mobile platform override ('android' | 'ios').
-     * When set, this takes precedence over log-based detection so callers that
-     * already know the target platform (e.g. the E2E script using adb) do not
-     * 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;
-    readonly flowResults: MaestroFlowResult[];
-    readonly aiDefects: AIDefect[];
-    readonly artifacts: CollectedArtifacts;
-}
-declare function orchestrateReport(input: OrchestratorInput): Promise<OrchestratorResult>;
-
-/**
- * CloudClient — manages cloud connectivity lifecycle for Maestro analytics.
- * Handles auth, repo resolution, token refresh, and queue flush.
- */
-
-declare class CloudClient {
-    private config;
-    private authState;
-    private gitMetadata;
-    private repoId;
-    private failureReason;
-    private flushPromise;
-    private healthCheckTimer;
-    constructor(cloudConfig: CloudConfig | null);
-    initialize(): Promise<void>;
-    getMode(): AuthMode;
-    isCloudMode(): boolean;
-    isLocalMode(): boolean;
-    getAccessToken(): string | null;
-    getRepoId(): string | null;
-    getGitMetadata(): GitMetadata | null;
-    getConfig(): CloudConfig | null;
-    getFailureReason(): string | null;
-    getEndpoint(): string;
-    ensureValidToken(): Promise<boolean>;
-    switchToLocalMode(reason: string): void;
-    dispose(): Promise<void>;
-    private setLocalMode;
-    private handleAuthError;
-    private resolveRepoId;
-    private readRepoCache;
-    private writeRepoCache;
-    private hashApiKey;
-    private startBackgroundFlush;
-    private startHealthCheck;
-}
-
 /**
  * Cloud upload — batch and realtime upload functions.
  * Adapted from appium-analytics with testFramework: 'maestro'.
@@ -523,6 +459,23 @@ interface TestResultForUpload {
      * via Ask AI's `query_network_logs` tool — works for free, no cloud changes.
      */
     readonly apiCalls?: readonly ApiCallRecord[];
+    /**
+     * Per-flow ActionStep array (mapped from Maestro `commands` + `assertions`,
+     * sorted by timestamp + sequenceNumber, with `retry`/`repeat` children
+     * nested under their wrapper and `videoOffset` computed from
+     * `flow.startedAt`). The cloud server's per-test ingest path
+     * (`server/src/services/run.service.ts:uploadTest` → `enrichTimeline` →
+     * OpenObserve `timeline_{orgId}` + RustFS `actions.json`) consumes this
+     * and powers the Session Workspace's Steps + Assertions tabs and Ask AI's
+     * `query_test_steps` tool.
+     *
+     * The same array also rides on `timeline[i].tests[j].actions` in the
+     * upload's `timeline` field — but the cloud's per-test ingest path keys off
+     * `tests[].actions`. Without this field, Maestro test detail pages show
+     * "No step data available" even though the run summary reports correct step
+     * counts. See issue #77.
+     */
+    readonly actions?: readonly ActionStep[];
 }
 interface RunUploadPayload {
     readonly runId: string;
@@ -581,6 +534,78 @@ declare function finalizeRun(endpoint: string, accessToken: string, cloudRunId:
     commitMessage?: string | null;
 }): Promise<boolean>;
 
+/**
+ * Report orchestrator — ties all parsers together to produce
+ * a TestRunReport from Maestro's output artifacts.
+ */
+
+interface OrchestratorInput {
+    readonly junitPath?: string;
+    readonly testOutputDir?: string;
+    readonly debugOutputDir?: string;
+    readonly flowsDir?: string;
+    readonly config: ResolvedMaestroConfig;
+    /** Device serial / name used during this run, e.g. "emulator-5554". Passed through to each flow result and uploaded as deviceName. */
+    readonly device?: string;
+    /**
+     * Explicit mobile platform override ('android' | 'ios').
+     * When set, this takes precedence over log-based detection so callers that
+     * already know the target platform (e.g. the E2E script using adb) do not
+     * 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;
+    readonly flowResults: MaestroFlowResult[];
+    readonly aiDefects: AIDefect[];
+    readonly artifacts: CollectedArtifacts;
+}
+declare function orchestrateReport(input: OrchestratorInput): Promise<OrchestratorResult>;
+
+/**
+ * CloudClient — manages cloud connectivity lifecycle for Maestro analytics.
+ * Handles auth, repo resolution, token refresh, and queue flush.
+ */
+
+declare class CloudClient {
+    private config;
+    private authState;
+    private gitMetadata;
+    private repoId;
+    private failureReason;
+    private flushPromise;
+    private healthCheckTimer;
+    constructor(cloudConfig: CloudConfig | null);
+    initialize(): Promise<void>;
+    getMode(): AuthMode;
+    isCloudMode(): boolean;
+    isLocalMode(): boolean;
+    getAccessToken(): string | null;
+    getRepoId(): string | null;
+    getGitMetadata(): GitMetadata | null;
+    getConfig(): CloudConfig | null;
+    getFailureReason(): string | null;
+    getEndpoint(): string;
+    ensureValidToken(): Promise<boolean>;
+    switchToLocalMode(reason: string): void;
+    dispose(): Promise<void>;
+    private setLocalMode;
+    private handleAuthError;
+    private resolveRepoId;
+    private readRepoCache;
+    private writeRepoCache;
+    private hashApiKey;
+    private startBackgroundFlush;
+    private startHealthCheck;
+}
+
 /**
  * Cloud reporter orchestration for Maestro analytics.
  * Handles batch upload and artifact upload to the TestRelic platform.

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { TestStatus, CloudReporterOptions, ReportMode, CloudConfig, ApiCallRecord, TimelineEntry, Summary, TestRunReport, AuthMode, GitMetadata, TimelineStep, CIMetadata } from '@testrelic/core';
+import { TestStatus, CloudReporterOptions, ReportMode, CloudConfig, ApiCallRecord, TimelineEntry, Summary, TestRunReport, TimelineStep, ActionStep, GitMetadata, CIMetadata, AuthMode } 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';
 
@@ -309,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[];
 
@@ -406,78 +414,6 @@ interface RunMaestroExtras {
 }
 declare function runMaestro(options: MaestroTestOptions, extras?: RunMaestroExtras): Promise<MaestroRunResult>;
 
-/**
- * Report orchestrator — ties all parsers together to produce
- * a TestRunReport from Maestro's output artifacts.
- */
-
-interface OrchestratorInput {
-    readonly junitPath?: string;
-    readonly testOutputDir?: string;
-    readonly debugOutputDir?: string;
-    readonly flowsDir?: string;
-    readonly config: ResolvedMaestroConfig;
-    /** Device serial / name used during this run, e.g. "emulator-5554". Passed through to each flow result and uploaded as deviceName. */
-    readonly device?: string;
-    /**
-     * Explicit mobile platform override ('android' | 'ios').
-     * When set, this takes precedence over log-based detection so callers that
-     * already know the target platform (e.g. the E2E script using adb) do not
-     * 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;
-    readonly flowResults: MaestroFlowResult[];
-    readonly aiDefects: AIDefect[];
-    readonly artifacts: CollectedArtifacts;
-}
-declare function orchestrateReport(input: OrchestratorInput): Promise<OrchestratorResult>;
-
-/**
- * CloudClient — manages cloud connectivity lifecycle for Maestro analytics.
- * Handles auth, repo resolution, token refresh, and queue flush.
- */
-
-declare class CloudClient {
-    private config;
-    private authState;
-    private gitMetadata;
-    private repoId;
-    private failureReason;
-    private flushPromise;
-    private healthCheckTimer;
-    constructor(cloudConfig: CloudConfig | null);
-    initialize(): Promise<void>;
-    getMode(): AuthMode;
-    isCloudMode(): boolean;
-    isLocalMode(): boolean;
-    getAccessToken(): string | null;
-    getRepoId(): string | null;
-    getGitMetadata(): GitMetadata | null;
-    getConfig(): CloudConfig | null;
-    getFailureReason(): string | null;
-    getEndpoint(): string;
-    ensureValidToken(): Promise<boolean>;
-    switchToLocalMode(reason: string): void;
-    dispose(): Promise<void>;
-    private setLocalMode;
-    private handleAuthError;
-    private resolveRepoId;
-    private readRepoCache;
-    private writeRepoCache;
-    private hashApiKey;
-    private startBackgroundFlush;
-    private startHealthCheck;
-}
-
 /**
  * Cloud upload — batch and realtime upload functions.
  * Adapted from appium-analytics with testFramework: 'maestro'.
@@ -523,6 +459,23 @@ interface TestResultForUpload {
      * via Ask AI's `query_network_logs` tool — works for free, no cloud changes.
      */
     readonly apiCalls?: readonly ApiCallRecord[];
+    /**
+     * Per-flow ActionStep array (mapped from Maestro `commands` + `assertions`,
+     * sorted by timestamp + sequenceNumber, with `retry`/`repeat` children
+     * nested under their wrapper and `videoOffset` computed from
+     * `flow.startedAt`). The cloud server's per-test ingest path
+     * (`server/src/services/run.service.ts:uploadTest` → `enrichTimeline` →
+     * OpenObserve `timeline_{orgId}` + RustFS `actions.json`) consumes this
+     * and powers the Session Workspace's Steps + Assertions tabs and Ask AI's
+     * `query_test_steps` tool.
+     *
+     * The same array also rides on `timeline[i].tests[j].actions` in the
+     * upload's `timeline` field — but the cloud's per-test ingest path keys off
+     * `tests[].actions`. Without this field, Maestro test detail pages show
+     * "No step data available" even though the run summary reports correct step
+     * counts. See issue #77.
+     */
+    readonly actions?: readonly ActionStep[];
 }
 interface RunUploadPayload {
     readonly runId: string;
@@ -581,6 +534,78 @@ declare function finalizeRun(endpoint: string, accessToken: string, cloudRunId:
     commitMessage?: string | null;
 }): Promise<boolean>;
 
+/**
+ * Report orchestrator — ties all parsers together to produce
+ * a TestRunReport from Maestro's output artifacts.
+ */
+
+interface OrchestratorInput {
+    readonly junitPath?: string;
+    readonly testOutputDir?: string;
+    readonly debugOutputDir?: string;
+    readonly flowsDir?: string;
+    readonly config: ResolvedMaestroConfig;
+    /** Device serial / name used during this run, e.g. "emulator-5554". Passed through to each flow result and uploaded as deviceName. */
+    readonly device?: string;
+    /**
+     * Explicit mobile platform override ('android' | 'ios').
+     * When set, this takes precedence over log-based detection so callers that
+     * already know the target platform (e.g. the E2E script using adb) do not
+     * 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;
+    readonly flowResults: MaestroFlowResult[];
+    readonly aiDefects: AIDefect[];
+    readonly artifacts: CollectedArtifacts;
+}
+declare function orchestrateReport(input: OrchestratorInput): Promise<OrchestratorResult>;
+
+/**
+ * CloudClient — manages cloud connectivity lifecycle for Maestro analytics.
+ * Handles auth, repo resolution, token refresh, and queue flush.
+ */
+
+declare class CloudClient {
+    private config;
+    private authState;
+    private gitMetadata;
+    private repoId;
+    private failureReason;
+    private flushPromise;
+    private healthCheckTimer;
+    constructor(cloudConfig: CloudConfig | null);
+    initialize(): Promise<void>;
+    getMode(): AuthMode;
+    isCloudMode(): boolean;
+    isLocalMode(): boolean;
+    getAccessToken(): string | null;
+    getRepoId(): string | null;
+    getGitMetadata(): GitMetadata | null;
+    getConfig(): CloudConfig | null;
+    getFailureReason(): string | null;
+    getEndpoint(): string;
+    ensureValidToken(): Promise<boolean>;
+    switchToLocalMode(reason: string): void;
+    dispose(): Promise<void>;
+    private setLocalMode;
+    private handleAuthError;
+    private resolveRepoId;
+    private readRepoCache;
+    private writeRepoCache;
+    private hashApiKey;
+    private startBackgroundFlush;
+    private startHealthCheck;
+}
+
 /**
  * Cloud reporter orchestration for Maestro analytics.
  * Handles batch upload and artifact upload to the TestRelic platform.