@elliemae/smoked-suite 26.2.15

package/dist/esm/page-setup/index.js

@@ -0,0 +1,96 @@
+class PageSetup {
+  /**
+   * Apply all page-level setup. Call once per test — each test
+   * receives a fresh Playwright page, so init scripts and route
+   * blocks do not carry over.
+   * @param page
+   */
+  async apply(page) {
+    await Promise.all([
+      this.stubDiagnostics(page),
+      this.suppressErrorOverlays(page)
+    ]);
+    await this.blockThirdPartyScripts(page);
+  }
+  /**
+   * Provide a no-op fallback for the emuiDiagnostics webpack external.
+   * @param page
+   */
+  async stubDiagnostics(page) {
+    await page.addInitScript(() => {
+      if (typeof window.emuiDiagnostics === "undefined") {
+        const noop = () => {
+        };
+        const noopTransport = { log: async () => true };
+        const fallbackLogger = new Proxy({}, {
+          get(_target, prop) {
+            if (typeof prop === "string" && typeof console[prop] === "function") {
+              return console[prop].bind(console);
+            }
+            return prop === "setOptions" ? noop : console.log.bind(console);
+          }
+        });
+        window.emuiDiagnostics = {
+          http: () => noopTransport,
+          logger: () => fallbackLogger,
+          Console: () => noopTransport,
+          logUnhandledErrors: noop,
+          webvitals: noop,
+          parentApp: () => noopTransport,
+          redactPii: (val) => val,
+          LogLevels: { DEBUG: 0, INFO: 1, WARN: 2, ERROR: 3, FATAL: 4 }
+        };
+      }
+    });
+  }
+  /**
+   * Auto-hide webpack / react-error-overlay iframes that obscure
+   * the page during tests.
+   * @param page
+   */
+  async suppressErrorOverlays(page) {
+    await page.addInitScript(() => {
+      const hideOverlayIframes = () => {
+        document.querySelectorAll("body > iframe").forEach((el) => {
+          el.style.display = "none";
+        });
+      };
+      const start = () => {
+        hideOverlayIframes();
+        new MutationObserver(hideOverlayIframes).observe(document.body, {
+          childList: true
+        });
+      };
+      if (document.body) start();
+      else document.addEventListener("DOMContentLoaded", start);
+    });
+  }
+  /** Domains that are blocked during tests to speed up page loads. */
+  static BLOCKED_DOMAINS = [
+    "googletagmanager.com",
+    "google-analytics.com",
+    "fonts.googleapis.com",
+    "fonts.gstatic.com",
+    "hotjar.com",
+    "newrelic.com",
+    "nr-data.net",
+    "sentry.io",
+    "fullstory.com",
+    "pendo.io"
+  ];
+  /** Single regex matching all {@link BLOCKED_DOMAINS}. */
+  static BLOCKED_PATTERN = new RegExp(
+    PageSetup.BLOCKED_DOMAINS.map((d) => d.replace(/\./g, "\\.")).join("|")
+  );
+  /**
+   * Block analytics, fonts, and monitoring scripts that slow page loads.
+   * Uses a single route handler instead of one per domain.
+   * @param page
+   */
+  async blockThirdPartyScripts(page) {
+    await page.route(PageSetup.BLOCKED_PATTERN, (route) => route.abort());
+  }
+}
+export {
+  PageSetup
+};

package/dist/esm/playwright-config/index.js

@@ -0,0 +1,92 @@
+import * as path from "path";
+import {
+  defineConfig,
+  devices
+} from "@playwright/test";
+import { STORAGE_FILE } from "../global-setup/index.js";
+import {
+  buildCoverageReporters,
+  configureCoverage
+} from "../monocartCoverage/index.js";
+const DEFAULT_ACTION_TIMEOUT = 3e4;
+const DEFAULT_NAVIGATION_TIMEOUT = 45e3;
+const DEFAULT_TEST_TIMEOUT = 12e4;
+const DEFAULT_EXPECT_TIMEOUT = 3e4;
+const FAST_MODE_USE = {
+  trace: "off",
+  screenshot: "off",
+  video: "off"
+};
+const DEFAULT_USE = {
+  trace: "retain-on-failure",
+  screenshot: "only-on-failure",
+  video: "retain-on-failure"
+};
+const CI_CONFIG = {
+  workers: "100%",
+  forbidOnly: true,
+  retries: 2,
+  reporter: [
+    ["list"],
+    ["junit", { outputFile: "playwright-report/junit.xml" }]
+  ]
+};
+const LOCAL_CONFIG = {
+  workers: "50%",
+  forbidOnly: false,
+  retries: 0,
+  reporter: [
+    ["html", { outputFolder: "playwright-report" }],
+    ["list"]
+  ]
+};
+function createPlaywrightConfig(params = {}) {
+  const {
+    overrides = {},
+    globalAuth = true,
+    fastMode = false,
+    coverage
+  } = params;
+  const { use: useOverrides, expect: expectOverrides, ...rest } = overrides;
+  const isCoverage = !!coverage;
+  if (isCoverage) configureCoverage();
+  const globalSetup = path.resolve(__dirname, "../global-setup/index.js");
+  const globalAuthConfig = globalAuth ? { globalSetup } : {};
+  const storageStateConfig = globalAuth ? { storageState: path.join(process.cwd(), STORAGE_FILE) } : {};
+  const envConfig = process.env.CI ? CI_CONFIG : LOCAL_CONFIG;
+  const coverageReporter = isCoverage ? { reporter: buildCoverageReporters(coverage) } : {};
+  return defineConfig({
+    testMatch: "**/*Spec.ts",
+    fullyParallel: true,
+    ...envConfig,
+    ...coverageReporter,
+    projects: [
+      {
+        name: "chromium",
+        use: { ...devices["Desktop Chrome"] }
+      }
+    ],
+    outputDir: "test-results",
+    timeout: DEFAULT_TEST_TIMEOUT,
+    ...globalAuthConfig,
+    ...rest,
+    use: {
+      ...fastMode ? FAST_MODE_USE : DEFAULT_USE,
+      viewport: { width: 1280, height: 720 },
+      actionTimeout: DEFAULT_ACTION_TIMEOUT,
+      navigationTimeout: DEFAULT_NAVIGATION_TIMEOUT,
+      ...storageStateConfig,
+      ...useOverrides,
+      ...{
+        baseURL: process.env.BASE_URL ?? useOverrides?.baseURL ?? "http://localhost:3000"
+      }
+    },
+    expect: {
+      timeout: DEFAULT_EXPECT_TIMEOUT,
+      ...expectOverrides
+    }
+  });
+}
+export {
+  createPlaywrightConfig
+};

package/dist/esm/routes/index.js

@@ -0,0 +1,7 @@
+function getRoutePath(routes, route) {
+  if (route in routes) return routes[route];
+  return route;
+}
+export {
+  getRoutePath
+};

package/dist/types/lib/auth/index.d.ts

@@ -0,0 +1,41 @@
+import { Page } from '@playwright/test';
+import { AuthState, Credentials } from '../types.js';
+/**
+ * Manages the encw authentication lifecycle.
+ *
+ * - Performs the Instance ID / User / Password login flow.
+ * - Snapshots the full session storage after login.
+ * - Injects the snapshot into fresh pages so subsequent tests
+ *   skip the login form entirely.
+ * - Detects expired sessions and forces re-login.
+ */
+export declare class AuthManager {
+    private static authState;
+    /** Whether a cached session exists and is still valid. */
+    hasValidAuth(): boolean;
+    /** Expose current auth state (used by global setup to serialise). */
+    static getAuthState(): AuthState | null;
+    /**
+     * Load auth state from the file written by globalSetup.
+     * Returns `true` if a valid (non-expired) session was loaded.
+     */
+    static loadFromFile(): boolean;
+    /**
+     * Restore every session-storage entry that was captured after
+     * the initial login so encw and its micro-apps find the data
+     * they need (Authorization, cred, user, userSettings, etc.).
+     * @param page
+     */
+    inject(page: Page): Promise<void>;
+    /**
+     * Snapshot every session-storage entry after a successful login.
+     * @param page
+     */
+    capture(page: Page): Promise<void>;
+    /**
+     * Perform the encw login flow (Instance ID -> User / Password).
+     * @param page  - Playwright page to drive.
+     * @param creds - Credentials to use.
+     */
+    login(page: Page, creds: Credentials): Promise<void>;
+}

package/dist/types/lib/base-page/index.d.ts

@@ -0,0 +1,27 @@
+import { Page, Locator } from '@playwright/test';
+import { AppContext, ContextProvider } from '../types.js';
+/**
+ * Base page object class for encw apps.
+ *
+ * Accepts a {@link ContextProvider}: either a direct Page or
+ * a callback that returns the current one. The callback form
+ * lets page objects lazily resolve the context.
+ * @example
+ * ```ts
+ * this.settingsPage = new MyPage(() => this.page);
+ * ```
+ */
+export declare abstract class BasePage {
+    private readonly _contextProvider;
+    /** The current Page context, resolved lazily. */
+    protected get page(): AppContext;
+    constructor(context: ContextProvider);
+    protected getByTestId(testId: string): Locator;
+    protected locator(selector: string): Locator;
+    protected getByRole(role: Parameters<Page['getByRole']>[0], options?: Parameters<Page['getByRole']>[1]): Locator;
+    protected getByText(text: string | RegExp, options?: Parameters<Page['getByText']>[1]): Locator;
+    protected getByLabel(text: string | RegExp, options?: Parameters<Page['getByLabel']>[1]): Locator;
+    protected getByPlaceholder(text: string | RegExp, options?: Parameters<Page['getByPlaceholder']>[1]): Locator;
+    protected getByAltText(text: string | RegExp, options?: Parameters<Page['getByAltText']>[1]): Locator;
+    protected getByTitle(text: string | RegExp, options?: Parameters<Page['getByTitle']>[1]): Locator;
+}

package/dist/types/lib/browserstack/index.d.ts

@@ -0,0 +1,59 @@
+/**
+ * BrowserStack platform configuration for a single browser/OS combo.
+ */
+export interface BrowserStackPlatform {
+    os: string;
+    osVersion: string;
+    browserName: string;
+    browserVersion?: string;
+}
+/**
+ * Options for {@link createBrowserStackConfig}.
+ * All fields are optional and fall back to sensible defaults.
+ */
+export interface BrowserStackOptions {
+    /** Project name shown on the BrowserStack dashboard. */
+    projectName?: string;
+    /** Build name shown on the dashboard. */
+    buildName?: string;
+    /** Build identifier template (supports `${BUILD_NUMBER}`). */
+    buildIdentifier?: string;
+    /** Browser/OS combinations to test on. */
+    platforms?: BrowserStackPlatform[];
+    /** Number of parallel sessions per platform. */
+    parallelsPerPlatform?: number;
+    /** Enable the local tunnel for localhost testing. */
+    browserstackLocal?: boolean;
+    /** Resolve all traffic through the local machine (fixes Host header issues). */
+    forceLocal?: boolean;
+    /** Capture debug screenshots. */
+    debug?: boolean;
+    /** Capture HAR network logs. */
+    networkLogs?: boolean;
+    /** Browser console log level. */
+    consoleLogs?: 'disable' | 'errors' | 'warnings' | 'info' | 'verbose';
+}
+/**
+ * Generate the contents of a `browserstack.yml` configuration file.
+ *
+ * Credentials are always read from environment variables
+ * (`BROWSERSTACK_USERNAME` and `BROWSERSTACK_ACCESS_KEY`)
+ * and are **never** hardcoded.
+ * @param options - Override any default configuration value.
+ * @returns The YAML string ready to be written to `browserstack.yml`.
+ * @example
+ * ```ts
+ * import { createBrowserStackConfig, writeBrowserStackConfig } from '@elliemae/smoked-suite';
+ *
+ * // Generate and write to project root
+ * writeBrowserStackConfig({ projectName: 'my-app' });
+ * ```
+ */
+export declare function createBrowserStackConfig(options?: BrowserStackOptions): string;
+/**
+ * Write a `browserstack.yml` file to the specified directory.
+ * @param options    - BrowserStack configuration options.
+ * @param targetDir  - Directory to write the file to (defaults to `process.cwd()`).
+ * @returns The absolute path of the written file.
+ */
+export declare function writeBrowserStackConfig(options?: BrowserStackOptions, targetDir?: string): string;

package/dist/types/lib/global-setup/index.d.ts

@@ -0,0 +1,16 @@
+import { type FullConfig } from '@playwright/test';
+declare const AUTH_FILE = ".smoked-suite-auth.json";
+declare const STORAGE_FILE = ".smoked-suite-storage.json";
+/**
+ * Playwright `globalSetup` function that authenticates once and
+ * persists the session for all workers.
+ *
+ * Writes two files to `process.cwd()`:
+ * - `.smoked-suite-auth.json` — serialised `sessionStorage` entries
+ * - `.smoked-suite-storage.json` — Playwright `storageState` (cookies + localStorage)
+ *
+ * Workers load these files at startup so they never need to log in.
+ * @param config
+ */
+export default function globalSetup(config: FullConfig): Promise<void>;
+export { AUTH_FILE, STORAGE_FILE };

package/dist/types/lib/index.d.ts

@@ -0,0 +1,10 @@
+export { BasePage } from './base-page/index.js';
+export { AuthManager } from './auth/index.js';
+export { PageSetup } from './page-setup/index.js';
+export { getRoutePath } from './routes/index.js';
+export { createPlaywrightConfig } from './playwright-config/index.js';
+export { default as globalSetup } from './global-setup/index.js';
+export { createBrowserStackConfig, writeBrowserStackConfig, } from './browserstack/index.js';
+export type { BrowserStackOptions, BrowserStackPlatform, } from './browserstack/index.js';
+export type { AppContext, ContextProvider, AuthState, GotoOptions, Credentials, SmokedSuiteConfig, } from './types.js';
+export type { CoverageConfig } from './monocartCoverage/index.js';

package/dist/types/lib/monocartCoverage/index.d.ts

@@ -0,0 +1,57 @@
+import { type Page, PlaywrightTestConfig } from '@playwright/test';
+/**
+ * Mark coverage as configured. Called by {@link createPlaywrightConfig}
+ * when a `coverage` config is provided — no env var needed.
+ * @internal
+ */
+export declare function configureCoverage(): void;
+/**
+ * Enable V8 coverage collection. Hooks into the browser context so that
+ * every new page automatically starts JS coverage and every closed page
+ * reports its coverage data to monocart.
+ * @internal
+ */
+export declare function startCoverage(): void;
+/**
+ * Collect coverage from any pages still open, then disable collection.
+ * @internal
+ */
+export declare function stopCoverage(): Promise<void>;
+/**
+ * Start V8 coverage on a page and track it for collection.
+ * Call this after the page is assigned to the test instance.
+ * @param page
+ * @internal
+ */
+export declare function trackPage(page: Page): Promise<void>;
+/**
+ * Collect and report V8 coverage from a tracked page.
+ * Call this before the page is destroyed.
+ * @param page
+ * @internal
+ */
+export declare function untrackPage(page: Page): Promise<void>;
+/**
+ * Coverage configuration accepted by {@link createPlaywrightConfig}.
+ */
+export interface CoverageConfig {
+    /**
+     * Path to the source directory (relative to repo root).
+     * All `.ts` / `.tsx` files inside this directory are included in the
+     * coverage report — files never loaded by any test appear as 0%.
+     * @example './src/features/dashboard'
+     */
+    sourceDir: string;
+    /**
+     * Directory where coverage output files are written.
+     * Defaults to `./coverage/<sourceDir-basename>`.
+     * @example './coverage/dashboard'
+     */
+    outputDir?: string;
+}
+/**
+ * Builds the full reporter array when coverage is enabled.
+ * @param configs
+ * @internal
+ */
+export declare function buildCoverageReporters(configs: CoverageConfig[]): PlaywrightTestConfig['reporter'];

package/dist/types/lib/page-setup/index.d.ts

@@ -0,0 +1,39 @@
+import { Page } from '@playwright/test';
+/**
+ * Registers init scripts and route blocks on a Playwright page.
+ *
+ * Handles:
+ * - `emuiDiagnostics` webpack-external stub (CDN unreachable in test)
+ * - Auto-hiding error-overlay iframes (webpack / react-error-overlay)
+ * - Blocking non-essential third-party scripts (analytics, tag manager)
+ */
+export declare class PageSetup {
+    /**
+     * Apply all page-level setup. Call once per test — each test
+     * receives a fresh Playwright page, so init scripts and route
+     * blocks do not carry over.
+     * @param page
+     */
+    apply(page: Page): Promise<void>;
+    /**
+     * Provide a no-op fallback for the emuiDiagnostics webpack external.
+     * @param page
+     */
+    private stubDiagnostics;
+    /**
+     * Auto-hide webpack / react-error-overlay iframes that obscure
+     * the page during tests.
+     * @param page
+     */
+    private suppressErrorOverlays;
+    /** Domains that are blocked during tests to speed up page loads. */
+    static readonly BLOCKED_DOMAINS: string[];
+    /** Single regex matching all {@link BLOCKED_DOMAINS}. */
+    static readonly BLOCKED_PATTERN: RegExp;
+    /**
+     * Block analytics, fonts, and monitoring scripts that slow page loads.
+     * Uses a single route handler instead of one per domain.
+     * @param page
+     */
+    private blockThirdPartyScripts;
+}

package/dist/types/lib/playwright-config/index.d.ts

@@ -0,0 +1,3 @@
+import { type PlaywrightTestConfig } from '@playwright/test';
+import type { SmokedSuiteConfig } from '../types.js';
+export declare function createPlaywrightConfig(params?: SmokedSuiteConfig): PlaywrightTestConfig;

package/dist/types/lib/routes/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Resolve a route key to a URL path.
+ *
+ * If `route` is a key in the provided `routes` map, returns the
+ * mapped path. Otherwise treats `route` as a raw path and returns
+ * it as-is.
+ * @param routes
+ * @param route
+ * @example
+ * ```ts
+ * const ROUTES = { home: '/app/home', settings: '/app/settings' } as const;
+ * getRoutePath(ROUTES, 'home');       // '/app/home'
+ * getRoutePath(ROUTES, '/raw/path');  // '/raw/path'
+ * ```
+ */
+export declare function getRoutePath<T extends Record<string, string>>(routes: T, route: keyof T | string): string;

package/dist/types/lib/types.d.ts

@@ -0,0 +1,77 @@
+import { Page } from '@playwright/test';
+/** Page context for element interaction. */
+export type AppContext = Page;
+/**
+ * A direct Page or a callback that returns the current Page.
+ * The callback form lets page objects lazily resolve the context.
+ */
+export type ContextProvider = AppContext | (() => AppContext);
+/**
+ * Full session storage snapshot captured after login.
+ * Includes Authorization, cred, user, userSettings, instanceId, etc.
+ */
+export interface AuthState {
+    /** All session storage entries needed to restore a logged-in session */
+    sessionEntries: Record<string, string>;
+    /** Timestamp when auth was captured */
+    capturedAt: number;
+}
+/**
+ * Credentials for login
+ */
+export interface Credentials {
+    username: string;
+    password: string;
+    instanceId?: string;
+}
+/**
+ * Options for goto navigation
+ */
+export interface GotoOptions {
+    /** Wait for specific load state */
+    waitUntil?: 'load' | 'domcontentloaded' | 'networkidle';
+    /** Custom timeout */
+    timeout?: number;
+}
+/**
+ * Configuration for {@link createPlaywrightConfig}.
+ */
+export interface SmokedSuiteConfig {
+    /** Partial Playwright config to merge with sensible defaults. */
+    overrides?: import('@playwright/test').PlaywrightTestConfig;
+    /**
+     * When `true` (default), a `globalSetup` function runs once before
+     * all workers to authenticate and persist the session to disk.
+     * Workers reuse it instead of logging in individually.
+     */
+    globalAuth?: boolean;
+    /**
+     * When `true`, disables trace, screenshot, and video recording
+     * for faster test execution.
+     */
+    fastMode?: boolean;
+    /**
+     * V8 code coverage configuration. When provided, monocart-reporter
+     * is automatically added to the reporter array and BaseTest collects
+     * V8 coverage per test. No env var needed.
+     *
+     * Pass a single config or an array for multi-app repos.
+     * Only `sourceDir` is required — everything else is derived.
+     * @example
+     * ```ts
+     * // Single app
+     * createPlaywrightConfig({
+     *   coverage: [{ sourceDir: './src/features/dashboard' }],
+     * });
+     *
+     * // Multi-app repo
+     * createPlaywrightConfig({
+     *   coverage: [
+     *     { sourceDir: './src/app-a' },
+     *     { sourceDir: './src/app-b' },
+     *   ],
+     * });
+     * ```
+     */
+    coverage?: import('./monocartCoverage/index.js').CoverageConfig[];
+}