@wdio/browserstack-service 9.36.2 → 9.39.0

package/build/cli/frameworks/wdioCucumberTestFramework.d.ts

@@ -0,0 +1,132 @@
+import TestFramework from './testFramework.js';
+import TestFrameworkInstance from '../instances/testFrameworkInstance.js';
+import type { Frameworks } from '@wdio/types';
+import type { CucumberHook, Feature } from '../../cucumber-types.js';
+type CucumberHookType = 'BEFORE_ALL' | 'AFTER_ALL' | 'BEFORE_EACH' | 'AFTER_EACH';
+/**
+ * CLI test framework for `framework: 'cucumber'` under WebdriverIO.
+ *
+ * Extends the BASE TestFramework, never WdioMochaTestFramework: WDIO does not call
+ * `beforeTest`/`afterTest`/titled hooks for cucumber at all, so mocha's INIT_TEST/TEST/hook
+ * boundary semantics have no source here and borrowing them would report cucumber through the
+ * wrong runner's event model.
+ *
+ * Cucumber's unit of work is the scenario, and every `cli/modules/*` observer subscribes to
+ * `TestFrameworkState.TEST` — so a scenario raises TEST/PRE at `beforeScenario` and TEST/POST at
+ * `afterScenario`, and the module set works unchanged.
+ */
+export default class WdioCucumberTestFramework extends TestFramework {
+    static KEY_HOOK_LAST_STARTED: string;
+    static KEY_HOOK_LAST_FINISHED: string;
+    /**
+     * The bookkeeping `classifyHookType()` derives hook types from. A cucumber hook invocation
+     * carries no title, and `BeforeAll`/`AfterAll` pass no hook object at all, so classification
+     * is state-machine derived — `util.ts → getHookType()` is Mocha-title-shaped and can only
+     * return 'unknown' or throw here.
+     */
+    private cucumberData;
+    /**
+     * Steps accumulated for the scenario in flight. Re-allocated (never cleared in place) at each
+     * scenario start so a payload already built from the previous scenario can never observe the
+     * next one's steps.
+     */
+    private scenarioSteps;
+    /** The hook currently open on this worker — started and not yet finished. */
+    private openHook;
+    constructor(testFrameworks: string[], testFrameworkVersions: Record<string, string>, binSessionId: string);
+    /**
+     * Feature bookkeeping. Raises no framework state — cucumber has no feature-level wire event,
+     * and `beforeSuite`/`afterSuite` are not part of its WDIO surface.
+     */
+    onFeatureStart(uri: string, feature: Feature): void;
+    /**
+     * Step bookkeeping. Steps travel inside the scenario payload's BDD meta, never as their own
+     * event — `TestFrameworkState.STEP` has zero producers anywhere in this SDK.
+     */
+    onStepStart(step: Frameworks.PickleStep): void;
+    onStepEnd(step: Frameworks.PickleStep, result: Frameworks.PickleResult): void;
+    /**
+     * Classify a cucumber hook invocation from the bookkeeping state.
+     *
+     * Returns null for a step-scoped hook (`BeforeStep`/`AfterStep`), which is never reported —
+     * reporting it would change the dashboard hook count, which is a feature and not parity.
+     */
+    classifyHookType(test: CucumberHook | undefined): CucumberHookType | null;
+    /** The TestFrameworkState a cucumber hook invocation maps to, or null when unreported. */
+    classifyHookState(test: CucumberHook | undefined): State | null;
+    /**
+     * `<HOOK_TYPE> for <scenario|feature name>` — the separator is a literal ' ' + 'for' + ' '.
+     */
+    private hookName;
+    private featurePath;
+    /**
+     * The feature path as the bdd meta blob wants it — cwd-relative, matching legacy.
+     *
+     * `cucumberData.uri` cannot be forwarded raw: WDIO hands `beforeFeature` an ABSOLUTE uri, so
+     * the raw value carries the developer's home directory. Legacy never sees that value — it
+     * reads the cucumber world's `gherkinDocument.uri`, which is cwd-relative.
+     */
+    private featureUriForMeta;
+    trackEvent(testFrameworkState: State, hookState: State, args?: Record<string, unknown>): Promise<void>;
+    /**
+     * One instance per scenario, keyed by the worker (`pid:threadId`) — the single lookup every
+     * `cli/modules/*` reads, via `TestFramework.getTrackedInstance()`. WDIO forks one worker
+     * process per spec file, so the worker key is the scenario's execution context; a thread id
+     * alone would collide once threads are reused.
+     */
+    private resolveInstance;
+    private trackWdioCucumberInstance;
+    /** Scenario identity. Each field matches what the legacy flow sent; the asymmetries are deliberate. */
+    private loadScenarioData;
+    /**
+     * `feature.path` is cwd-relative, matching legacy (`insights-handler` builds
+     * `feature = { path: gherkinDocument.uri, … }` off the cucumber world). It is NOT the absolute
+     * path used for `test_file_path`: the binary re-bases that one, but never touches this blob, so
+     * an absolute value here reaches the dashboard as-is, home directory and all.
+     */
+    private buildBddMetaInfo;
+    /**
+     * Scenario result, loaded at the real "scenario ends" state.
+     *
+     * KEY_TEST_RESULT_AT is load-bearing, not decoration: `testHubModule → onAllTestEvents()`
+     * treats a TEST/POST without it as result-less, marks the test deferred, and then waits for a
+     * `LOG_REPORT` POST to recover it — a state cucumber never emits.
+     */
+    private loadScenarioResult;
+    /**
+     * One detached instance per scenario the feature never ran, for the BEFORE_ALL cascade
+     * (Rule-nested included). Detached is load-bearing: not registered via `setTrackedInstance`,
+     * so the live instance and `process.env[TEST_ANALYTICS_ID]` are untouched, and the caller
+     * sends each straight to TestHub — routing them through the observers would rename the
+     * session, stop accessibility and run a Percy teardown per row. No tags: legacy's cascade
+     * payload has no `world`.
+     */
+    buildSkippedScenarioInstances(): TestFrameworkInstance[];
+    private buildSkippedScenarioInstance;
+    /**
+     * Whether the scenario in flight failed in a STEP, as opposed to failing only in a hook.
+     * Public because `ignoreHooksStatus` has two surfaces: the o11y result below, and the Automate
+     * session status, which `service.afterScenario()` derives from the same answer.
+     */
+    hasStepFailures(): boolean;
+    /**
+     * Route a console log to the row it belongs on: the open hook's uuid while a hook is in
+     * flight and unfinished, otherwise the scenario's uuid.
+     *
+     * The record itself always goes into KEY_TEST_LOGS, because the send path
+     * (`testHubModule → onAllTestEvents`, unchanged) collects test logs plus the last FINISHED
+     * hook's logs — a record parked on a still-open hook's own array would never be picked up.
+     * The routing is carried by KEY_HOOK_ID on the record, which `sendLogCreatedEvent` reads in
+     * preference to the test uuid.
+     */
+    private loadLogEntry;
+    /**
+     * Hook lifecycle. Entries are keyed by the short state name, matching how the binary looks
+     * them up via `event.test_hooks_started[request.testFrameworkState]`.
+     *
+     * A finish with no recorded start is dropped rather than emitted — an unmatched
+     * HookRunFinished orphans a hook row the backend cannot pair.
+     */
+    private trackHookEvents;
+}
+export {};

package/build/cli/grpcClient.d.ts

@@ -51,6 +51,26 @@ export declare class GrpcClient {
      * @private
      */
     stopBinSession(): Promise<unknown>;
+    /**
+     * Render end-of-build customer-visible summary entries.
+     *
+     * Per the binary proto contract (CustomerVisibleSummaryEntry in
+     * sdk-messages.proto): iterate by `severity` + `body`, write `body` verbatim,
+     * and pick the stream from `severity`. Never branches on `entryType`, so new
+     * entry types need no SDK change.
+     * @private
+     */
+    private renderCustomerVisibleSummary;
+    /**
+     * Tint a summary block by severity — yellow for warn (an outdated SDK), red for
+     * error (a deprecated one), untouched otherwise.
+     *
+     * Each line is wrapped and reset on its own rather than the block as a whole, so
+     * a truncated or interleaved write cannot leave the customer's terminal stuck in
+     * colour. The first non-blank, non-border line is emphasised.
+     * @private
+     */
+    private colouriseSummaryBody;
     testSessionEvent(data: Omit<TestSessionEventRequest, 'binSessionId'>): Promise<TestSessionEventResponse | undefined>;
     /**
      *

package/build/cli/index.d.ts

@@ -4,6 +4,7 @@ import type { StartBinSessionResponse } from '../grpc/index.js';
 import type BaseModule from './modules/baseModule.js';
 import type { Options } from '@wdio/types';
 import WdioMochaTestFramework from './frameworks/wdioMochaTestFramework.js';
+import WdioCucumberTestFramework from './frameworks/wdioCucumberTestFramework.js';
 import WdioAutomationFramework from './frameworks/wdioAutomationFramework.js';
 import type { BrowserstackConfig, BrowserstackOptions } from '../types.js';
 /**
@@ -26,7 +27,7 @@ export declare class BrowserstackCLI {
     modulesLoaded: boolean;
     binSessionId: string | null;
     modules: Record<string, BaseModule>;
-    testFramework: WdioMochaTestFramework | null;
+    testFramework: WdioMochaTestFramework | WdioCucumberTestFramework | null;
     cliParams: Record<string, string> | null;
     automationFramework: WdioAutomationFramework | null;
     SDK_CLI_BIN_PATH: string | null;
@@ -152,7 +153,7 @@ export declare class BrowserstackCLI {
      * Get the test framework
      * @returns {Object} The test framework
      */
-    getTestFramework(): WdioMochaTestFramework | null;
+    getTestFramework(): WdioMochaTestFramework | WdioCucumberTestFramework | null;
     /**
      * Get the automation framework
      * @returns {Object} The automation framework

package/build/cli/modules/automateModule.d.ts

@@ -18,8 +18,39 @@ export default class AutomateModule extends BaseModule {
      */
     private flushSessionName;
     onAfterTest(args: Record<string, unknown>): Promise<void>;
+    /**
+     * A `BeforeAll` / `AfterAll` failure produces no scenario result, so it can never enter the
+     * per-test `testResults` map that onAfterExecute aggregates — a run whose BeforeAll blew up
+     * reports its session as PASSED. Legacy pushed the hook error into `_failReasons` and
+     * `after()` marked the session failed; that whole accumulation is gated
+     * `setSessionStatus && !BrowserstackCLI.isRunning()`, so it is dead while the binary is up.
+     *
+     * Cucumber-gated deliberately. `wdio_mocha` has the identical latent shape on this flow, but
+     * legacy mocha behaved the same way, so repairing it here would be an unrequested behaviour
+     * change to the one framework already working on the CLI flow.
+     */
+    onBuildLevelHookEnd(hookKey: string, args: Record<string, unknown>): Promise<void>;
+    private isCucumberInstance;
+    /** The hook's reported name (`BEFORE_ALL for <feature>`), so the session reason names the hook. */
+    private resolveHookName;
     onAfterExecute(): Promise<void>;
     private isAppAutomate;
+    private isTurboScale;
+    /**
+     * Resolve the REST endpoint a session marker must hit.
+     *
+     * Turboscale is not a variant of Automate here — it is a different API on a different path
+     * with a different VERB (PATCH, not PUT). The legacy path expressed this through
+     * `_sessionBaseUrl` + `_update()`, both gated `!BrowserstackCLI.isRunning()`, so neither
+     * survives onto the CLI flow and nothing in the binary compensates.
+     *
+     * Precedence mirrors legacy's assignment order in `beforeSession()`: the turboscale base URL
+     * is assigned AFTER the app-automate one, so a turboscale grid wins even with an app cap set.
+     *
+     * Single resolver for both markers deliberately: naming and status previously duplicated the
+     * ternary, which is how the two can drift apart.
+     */
+    private resolveSessionApi;
     markSessionName(sessionId: string, sessionName: string, config: {
         user: string;
         key: string;

package/build/cli/modules/customTagsModule.d.ts

@@ -28,6 +28,7 @@ export default class CustomTagsModule extends BaseModule {
     private pendingTestLevelTags;
     constructor();
     getModuleName(): string;
+    private isMochaFramework;
     onBeforeExecute(): Promise<void>;
     /**
      * At each test start (TEST/PRE — after beforeTest tracks the instance), flush any

package/build/grpc/generated/sdk-messages.d.ts

@@ -146,6 +146,27 @@ export interface StopBinSessionResponse {
     error?: string | undefined;
     automateBuildlink?: string | undefined;
     hashedId?: string | undefined;
+    /**
+     * End-of-build customer-visible summary entries. Populated on EVERY response
+     * shape — success, error, and clean-build alike (empty when nothing to
+     * surface). Iterate by `severity` + `body`; do not branch on `entry_type`,
+     * so new entry types need no SDK change.
+     */
+    entries: CustomerVisibleSummaryEntry[];
+}
+/**
+ * A single customer-visible summary entry surfaced at end of build via
+ * StopBinSessionResponse.entries. The binary owns the prose so all SDKs render
+ * consistent text; SDKs choose the output stream from `severity`.
+ */
+export interface CustomerVisibleSummaryEntry {
+    /** Stable machine-readable identifier (e.g. "network_restrictions"). */
+    entryType: string;
+    /** One of: "info" | "warn" | "error". */
+    severity: string;
+    /** Pre-formatted block to display verbatim. May contain embedded newlines. */
+    body: string;
+    docLink?: string | undefined;
 }
 export interface ConnectBinSessionRequest {
     binSessionId: string;
@@ -265,6 +286,7 @@ export declare const TestOrchestrationRequest: MessageFns<TestOrchestrationReque
 export declare const TestOrchestrationResponse: MessageFns<TestOrchestrationResponse>;
 export declare const StopBinSessionRequest: MessageFns<StopBinSessionRequest>;
 export declare const StopBinSessionResponse: MessageFns<StopBinSessionResponse>;
+export declare const CustomerVisibleSummaryEntry: MessageFns<CustomerVisibleSummaryEntry>;
 export declare const ConnectBinSessionRequest: MessageFns<ConnectBinSessionRequest>;
 export declare const TestFrameworkEventRequest: MessageFns<TestFrameworkEventRequest>;
 export declare const ExecutionContext: MessageFns<ExecutionContext>;