@stencil/playwright 0.0.0-dev

package/dist/load-config-meta.d.ts

@@ -0,0 +1,13 @@
+/**
+ * For internal use only.
+ *
+ * Loads and validates the project's Stencil config.
+ *
+ * @returns The processed Stencil config metadata.
+ */
+export declare const loadConfigMeta: () => Promise<{
+    baseURL: string;
+    webServerUrl: string;
+    stencilNamespace: string;
+    stencilEntryPath: string;
+}>;

package/dist/matchers/index.d.ts

@@ -0,0 +1,12 @@
+import { toHaveFirstReceivedEventDetail } from './to-have-first-received-event-detail';
+import { toHaveNthReceivedEventDetail } from './to-have-nth-received-event-detail';
+import { toHaveReceivedEvent } from './to-have-received-event';
+import { toHaveReceivedEventDetail } from './to-have-received-event-detail';
+import { toHaveReceivedEventTimes } from './to-have-received-event-times';
+export declare const matchers: {
+    toHaveReceivedEvent: typeof toHaveReceivedEvent;
+    toHaveReceivedEventDetail: typeof toHaveReceivedEventDetail;
+    toHaveReceivedEventTimes: typeof toHaveReceivedEventTimes;
+    toHaveFirstReceivedEventDetail: typeof toHaveFirstReceivedEventDetail;
+    toHaveNthReceivedEventDetail: typeof toHaveNthReceivedEventDetail;
+};

package/dist/matchers/to-have-first-received-event-detail.d.ts

@@ -0,0 +1,5 @@
+import { EventSpy } from '../page/event-spy';
+export declare function toHaveFirstReceivedEventDetail(eventSpy: EventSpy, eventDetail: any): {
+    message: () => string;
+    pass: boolean;
+};

package/dist/matchers/to-have-nth-received-event-detail.d.ts

@@ -0,0 +1,5 @@
+import { EventSpy } from '../page/event-spy';
+export declare function toHaveNthReceivedEventDetail(eventSpy: EventSpy, index: number, eventDetail: any): {
+    message: () => string;
+    pass: boolean;
+};

package/dist/matchers/to-have-received-event-detail.d.ts

@@ -0,0 +1,5 @@
+import type { EventSpy } from '../page/event-spy';
+export declare function toHaveReceivedEventDetail(eventSpy: EventSpy, eventDetail: any): {
+    message: () => string;
+    pass: boolean;
+};

package/dist/matchers/to-have-received-event-times.d.ts

@@ -0,0 +1,5 @@
+import type { EventSpy } from '../page/event-spy';
+export declare function toHaveReceivedEventTimes(eventSpy: EventSpy, count: number): {
+    message: () => string;
+    pass: boolean;
+};

package/dist/matchers/to-have-received-event.d.ts

@@ -0,0 +1,5 @@
+import type { EventSpy } from '../page/event-spy';
+export declare function toHaveReceivedEvent(eventSpy: EventSpy): {
+    message: () => string;
+    pass: boolean;
+};

package/dist/page/event-spy.d.ts

@@ -0,0 +1,44 @@
+import type { JSHandle } from '@playwright/test';
+import type { E2EPage } from '../playwright-declarations';
+/**
+ * The EventSpy class allows developers to listen for a particular event emission and
+ * pass/fail the test based on whether or not the event was emitted.
+ * Based off https://github.com/ionic-team/stencil/blob/16b8ea4dabb22024872a38bc58ba1dcf1c7cc25b/src/testing/puppeteer/puppeteer-events.ts#L64
+ */
+export declare class EventSpy {
+    eventName: string;
+    /**
+     * Keeping track of a cursor ensures that no two spy.next() calls point to the same event.
+     */
+    private cursor;
+    private queuedHandler;
+    events: CustomEvent[];
+    constructor(eventName: string);
+    get length(): number;
+    get firstEvent(): CustomEvent<any>;
+    get lastEvent(): CustomEvent<any>;
+    next(): Promise<CustomEvent<any>>;
+    push(ev: CustomEvent): void;
+}
+/**
+ * For internal use only.
+ *
+ * Initializes information required to spy on events.
+ * The stencilOnEvent function is called in the context of the current page.
+ * This lets us respond to an event listener created within the page itself.
+ *
+ * @param page The Playwright test page object.
+ */
+export declare const initPageEvents: (page: E2EPage) => Promise<void>;
+/**
+ * For internal use only.
+ *
+ * Adds a new event listener in the current page context to updates
+ * the _e2eEvents map when an event is fired.
+ *
+ * @param page The Playwright test page object.
+ * @param elmHandle A {@link JSHandle} representing the element to listen for events on.
+ * @param eventName The event name to listen for.
+ * @param callback The callback to execute when the event is fired.
+ */
+export declare const addE2EListener: (page: E2EPage, elmHandle: JSHandle, eventName: string, callback: (ev: any) => void) => Promise<void>;

package/dist/page/utils/goto.d.ts

@@ -0,0 +1,12 @@
+import type { Page } from '@playwright/test';
+import type { E2EPageOptions } from '../../playwright-declarations';
+/**
+ * This is an extended version of Playwright's `page.goto` method. In addition to performing
+ * the normal `page.goto` work, this code also automatically waits for the Stencil components
+ * to be hydrated before proceeding with the test.
+ */
+export declare const goto: (page: Page, url: string, originalFn: (url: string, options?: {
+    referer?: string | undefined;
+    timeout?: number | undefined;
+    waitUntil?: "load" | "domcontentloaded" | "networkidle" | "commit" | undefined;
+} | undefined) => Promise<import("playwright-core").Response | null>, options?: E2EPageOptions) => Promise<import("playwright-core").Response | null>;

package/dist/page/utils/index.d.ts

@@ -0,0 +1,5 @@
+export * from './goto';
+export * from './locator';
+export * from './set-content';
+export * from './spy-on-event';
+export * from './wait-for-changes';

package/dist/page/utils/locator.d.ts

@@ -0,0 +1,21 @@
+import type { Locator } from '@playwright/test';
+import type { E2EPage } from '../../playwright-declarations';
+import { EventSpy } from '../event-spy';
+export type LocatorOptions = {
+    hasText?: string | RegExp;
+    has?: Locator;
+};
+export interface E2ELocator extends Locator {
+    /**
+     * Creates a new EventSpy and listens on the element for an event.
+     * The test will timeout if the event never fires.
+     *
+     * Usage:
+     * const input = page.locator('ion-input');
+     * const ionChange = await locator.spyOnEvent('ionChange');
+     * ...
+     * await ionChange.next();
+     */
+    spyOnEvent: (eventName: string) => Promise<EventSpy>;
+}
+export declare const locator: (page: E2EPage, originalFn: (selector: string, options?: LocatorOptions | undefined) => E2ELocator, selector: string, options?: LocatorOptions) => E2ELocator;

package/dist/page/utils/set-content.d.ts

@@ -0,0 +1,14 @@
+import type { Page, TestInfo } from '@playwright/test';
+import type { E2EPageOptions } from '../../playwright-declarations';
+/**
+ * Overwrites the default Playwright page.setContent method.
+ *
+ * Navigates to a blank page, sets the content, and waits for the
+ * Stencil components to be hydrated before proceeding with the test.
+ *
+ * @param page The Playwright page object.
+ * @param html The HTML content to set on the page.
+ * @param testInfo Test information from the test bed. Used to access base URL.
+ * @param options The test config associated with the current test run.
+ */
+export declare const setContent: (page: Page, html: string, testInfo: TestInfo, options?: E2EPageOptions) => Promise<void>;

package/dist/page/utils/spy-on-event.d.ts

@@ -0,0 +1,3 @@
+import type { E2EPage } from '../../playwright-declarations';
+import { EventSpy } from '../event-spy';
+export declare const spyOnEvent: (page: E2EPage, eventName: string) => Promise<EventSpy>;

package/dist/page/utils/wait-for-changes.d.ts

@@ -0,0 +1,11 @@
+import type { Page } from '@playwright/test';
+/**
+ * Waits for a combined threshold of a Stencil web component to be re-hydrated in the next repaint + 100ms.
+ * Used for testing changes to a web component that does not modify CSS classes or introduce new DOM nodes.
+ *
+ * Original source: https://github.com/ionic-team/stencil/blob/main/src/testing/puppeteer/puppeteer-page.ts#L298-L363
+ *
+ * @param page The Playwright page object.
+ * @param timeoutMs The time to wait for the changes to occur.
+ */
+export declare const waitForChanges: (page: Page, timeoutMs?: number) => Promise<void>;

package/dist/playwright-declarations.d.ts

@@ -0,0 +1,105 @@
+import type { Page, Response } from '@playwright/test';
+import type { EventSpy } from './page/event-spy';
+import type { E2ELocator, LocatorOptions } from './page/utils/locator';
+export interface E2EPageOptions extends PageOptions {
+}
+interface PageOptions {
+    /**
+     * Referer header value. If provided it will take preference over the referer header value set by
+     * [page.setExtraHTTPHeaders(headers)](https://playwright.dev/docs/api/class-page#page-set-extra-http-headers).
+     */
+    referer?: string;
+    /**
+     * Maximum operation time in milliseconds, defaults to 30 seconds, pass `0` to disable timeout. The default value can be
+     * changed by using the
+     * [browserContext.setDefaultNavigationTimeout(timeout)](https://playwright.dev/docs/api/class-browsercontext#browser-context-set-default-navigation-timeout),
+     * [browserContext.setDefaultTimeout(timeout)](https://playwright.dev/docs/api/class-browsercontext#browser-context-set-default-timeout),
+     * [page.setDefaultNavigationTimeout(timeout)](https://playwright.dev/docs/api/class-page#page-set-default-navigation-timeout)
+     * or [page.setDefaultTimeout(timeout)](https://playwright.dev/docs/api/class-page#page-set-default-timeout) methods.
+     */
+    timeout?: number;
+    /**
+     * When to consider operation succeeded, defaults to `load`. Events can be either:
+     * - `'domcontentloaded'` - consider operation to be finished when the `DOMContentLoaded` event is fired.
+     * - `'load'` - consider operation to be finished when the `load` event is fired.
+     * - `'networkidle'` - consider operation to be finished when there are no network connections for at least `500` ms.
+     * - `'commit'` - consider operation to be finished when network response is received and the document started loading.
+     */
+    waitUntil?: 'load' | 'domcontentloaded' | 'networkidle' | 'commit';
+}
+export interface E2EPage extends Page {
+    /**
+     * Returns the main resource response. In case of multiple redirects, the navigation will resolve with the response of the
+     * last redirect.
+     *
+     * The method will throw an error if:
+     * - there's an SSL error (e.g. in case of self-signed certificates).
+     * - target URL is invalid.
+     * - the `timeout` is exceeded during navigation.
+     * - the remote server does not respond or is unreachable.
+     * - the main resource failed to load.
+     *
+     * The method will not throw an error when any valid HTTP status code is returned by the remote server, including 404 "Not
+     * Found" and 500 "Internal Server Error".  The status code for such responses can be retrieved by calling
+     * [response.status()](https://playwright.dev/docs/api/class-response#response-status).
+     *
+     * > NOTE: The method either throws an error or returns a main resource response. The only exceptions are navigation to
+     * `about:blank` or navigation to the same URL with a different hash, which would succeed and return `null`.
+     * > NOTE: Headless mode doesn't support navigation to a PDF document. See the
+     * [upstream issue](https://bugs.chromium.org/p/chromium/issues/detail?id=761295).
+     *
+     * Shortcut for main frame's [frame.goto(url[, options])](https://playwright.dev/docs/api/class-frame#frame-goto)
+     * @param url URL to navigate page to. The url should include scheme, e.g. `https://`. When a `baseURL` via the context options was
+     * provided and the passed URL is a path, it gets merged via the [`new URL()`](https://developer.mozilla.org/en-US/docs/Web/API/URL/URL) constructor.
+     */
+    goto: (url: string, options?: E2EPageOptions) => Promise<null | Response>;
+    /**
+     * Assigns HTML markup to a page.
+     * @param html - The HTML markup to assign to the page
+     * @param options - Ionic config options or Playwright options for the page
+     */
+    setContent: (html: string, options?: E2EPageOptions) => Promise<void>;
+    /**
+     * Find an element by selector.
+     * See https://playwright.dev/docs/locators for more information.
+     */
+    locator: (selector: string, options?: LocatorOptions) => E2ELocator;
+    /**
+     * Increases the size of the page viewport to match the `ion-content` contents.
+     * Use this method when taking full-screen screenshots.
+     */
+    setIonViewport: (options?: SetIonViewportOptions) => Promise<void>;
+    /**
+     * After changes have been made to a component, such as an update to a property or attribute,
+     * we need to wait until the changes have been applied to the DOM.
+     */
+    waitForChanges: (timeoutMs?: number) => Promise<void>;
+    /**
+     * Creates a new EventSpy and listens on the window for an event.
+     * The test will timeout if the event never fires.
+     *
+     * Usage:
+     * ```ts
+     * const ionChange = await page.spyOnEvent('ionChange');
+     * ...
+     * await ionChange.next();
+     * ```
+     */
+    spyOnEvent: (eventName: string) => Promise<EventSpy>;
+    _e2eEventsIds: number;
+    _e2eEvents: Map<number, any>;
+}
+type BrowserName = 'chromium' | 'firefox' | 'webkit';
+export type BrowserNameOrCallback = BrowserName | ((browserName: BrowserName) => boolean);
+export interface E2ESkip {
+    browser: (browserNameOrCallback: BrowserNameOrCallback, reason?: string) => void;
+    mode: (mode: string, reason?: string) => void;
+}
+export interface SetIonViewportOptions {
+    /**
+     * `true` if the viewport should be scaled to match the `ion-content`
+     * scrollable width. Defaults to `false`.
+     */
+    resizeViewportWidth?: boolean;
+}
+export {};

package/dist/playwright-page.d.ts

@@ -0,0 +1,8 @@
+import type { PlaywrightTestArgs, PlaywrightTestOptions, PlaywrightWorkerArgs, PlaywrightWorkerOptions } from '@playwright/test';
+import type { E2EPage, E2ESkip } from './playwright-declarations';
+type CustomFixtures = {
+    page: E2EPage;
+    skip: E2ESkip;
+};
+export declare const test: import("@playwright/test").TestType<PlaywrightTestArgs & PlaywrightTestOptions & CustomFixtures, PlaywrightWorkerArgs & PlaywrightWorkerOptions>;
+export {};

package/dist/process-constants.d.ts

@@ -0,0 +1,4 @@
+export declare enum ProcessConstants {
+    STENCIL_NAMESPACE = "STENCIL_NAMESPACE",
+    STENCIL_ENTRY_PATH = "STENCIL_ENTRY_PATH"
+}

package/dist/test-expect.d.ts

@@ -0,0 +1,22 @@
+interface CustomMatchers<R = unknown> {
+    /**
+     * Will check if the event spy received the expected event.
+     */
+    toHaveReceivedEvent(): R;
+    /**
+     * Will check if the event spy received the expected event with the expected detail.
+     * @param eventDetail The expected detail of the event.
+     */
+    toHaveReceivedEventDetail(eventDetail: any): R;
+    /**
+     * Will check how many times the event has been received.
+     */
+    toHaveReceivedEventTimes(count: number): R;
+}
+declare global {
+    namespace PlaywrightTest {
+        interface Matchers<R> extends CustomMatchers<R> {
+        }
+    }
+}
+export {};

package/package.json

@@ -0,0 +1,76 @@
+{
+  "name": "@stencil/playwright",
+  "version": "0.0.0-dev",
+  "description": "Testing adapter to use Playwright with Stencil",
+  "main": "dist/index.cjs",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "npm run build.empty && npm run build.types && npm run build.bundle",
+    "build.empty": "rm -rf ./dist && rm -f ./build/build.js",
+    "build.types": "tsc --emitDeclarationOnly --outDir ./dist",
+    "build.bundle": "tsc ./build/build.ts && node ./build/build.js",
+    "format": "npm run format.base -- --write",
+    "format.base": "prettier --cache \"src/**/*.ts\"",
+    "format.dry-run": "npm run format.base -- --list-different",
+    "lint": "eslint \"src/**/*.ts\"",
+    "spellcheck": "cspell --no-progress \"src/**/*.ts\" \"build/**/*.ts\" \"*.md\"",
+    "test": "jest"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ionic-team/stencil-playwright.git"
+  },
+  "keywords": [
+    "stencil",
+    "playwright",
+    "testing"
+  ],
+  "author": "Stencil Team",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/ionic-team/stencil-playwright/issues"
+  },
+  "homepage": "https://github.com/ionic-team/stencil-playwright#readme",
+  "engines": {
+    "node": ">=12.0.0",
+    "npm": ">=6.0.0"
+  },
+  "volta": {
+    "node": "20.11.1",
+    "npm": "10.4.0"
+  },
+  "peerDependencies": {
+    "@playwright/test": ">=1.41.2",
+    "@stencil/core": ">=4.13.0"
+  },
+  "devDependencies": {
+    "@ionic/prettier-config": "^4.0.0",
+    "@playwright/test": "^1.41.2",
+    "@stencil/core": "^4.13.0",
+    "@types/eslint": "^8.56.2",
+    "@types/jest": "^29.5.12",
+    "@types/node": "^20.11.19",
+    "@typescript-eslint/eslint-plugin": "^7.0.2",
+    "@typescript-eslint/parser": "^7.0.2",
+    "cspell": "^8.6.0",
+    "esbuild": "^0.20.1",
+    "eslint": "^8.56.0",
+    "eslint-config-prettier": "^9.1.0",
+    "eslint-plugin-jsdoc": "^48.2.0",
+    "eslint-plugin-simple-import-sort": "^12.0.0",
+    "eslint-plugin-unused-imports": "^3.1.0",
+    "jest": "^29.7.0",
+    "prettier": "^3.2.5",
+    "ts-jest": "^29.1.2",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.3.3"
+  },
+  "prettier": "@ionic/prettier-config",
+  "dependencies": {
+    "glob": "^10.3.10"
+  }
+}