testable-playwright-test/index.d.ts

Playwright fixture to run your tests against Testable Cloud

import * as playwrightTest from '@playwright/test';

export interface Options {
    /**
     * Testable API key found at Org Management => API Keys on the Testable portal; required for remote tests.
     */
    key: string;

    /**
     * If you want Testable to take a screenshot of the browser after each test (afterEvery) or after each failed test (afterFailed)
     * you can use this option.
     */
    screenshot?: "afterEvery" | "afterFailed" | "none";

    /**
     * The browser version to test against. "Latest" by default. Supports "Latest-X" syntax (e.g. Latest-1 is the version before the most recent).
     * Can also choose a specific version (e.g. 114) or Beta for the latest beta release.
     */
    browserVersion?: string;

    /**
     * The region in which to launch the browsers. Defaults to aws-us-east-1 (public shared test runners in AWS N. Virginia).
     * See https://a.testable.io/remote-configurator for list of options.
     */
    region?: string;

    /**
     * To run your test on a per-test VM, specify the source here. See https://a.testable.io/remote-configurator for list of options.
     */
    source?: string;

    /**
     * For tests that run on per-test VMs you can associate an elastic IP to the instance if you have purchased one or the VMs are 
     * spun up in your cloud account. Valid values include "any" to choose any available elastic IP or a specific IPv4 address like "1.2.3.4".
     */
    elasticIps?: string;

    /**
     * Whether or not to force reassociate the chosen elastic IP to your test even if it is currently attached to another instance. Defaults to false.
     */
    forceAssociateElasticIps?: boolean;

    /**
     * Assign your test more VM resources. By default each browser gets 1 vCPU + 4GB RAM. Valid values include 1, 2, 4. If you choose 2 for example the
     * browser will receive 2 vCPU + 8GB RAM.
     */
    multiplier?: string;

    /**
     * Testable organizes tests into a 4 level hierarchy: Organization -> Test Case -> Scenario -> Test Configuration. Use this hierarchy to organize your
     * tests in a way that makes most sense to your team. Defaults to "Remote Playwright Tests".
     */
    testCaseName?: string;

    /**
     * Testable organizes tests into a 4 level hierarchy: Organization -> Test Case -> Scenario -> Test Configuration. Use this hierarchy to organize your
     * tests in a way that makes most sense to your team. Defaults to the name of the spec file (e.g. example.spec.ts).
     */
    scenarioName?: string;

    /**
     * The test configuration name. Testable organizes tests into a 4 level hierarchy: Organization -> Test Case -> Scenario -> Test Configuration. 
     * Use this hierarchy to organize your tests in a way that makes most sense to your team. 
     * Defaults to "[spec name] -> [test name]" (e.g. "example.spec.ts -> has title").
     */
    name?: string;

    /**
     * A user provided special tag for grouping together related test runs that are part of the same test session.
     */
    reportId?: string;

    /**
     * A comma separated list of tags to associate with any test run that uses this fixture. That are useful for finding related tests later.
     */
    tags?: string;

    /**
     * A unique identifier generated from createOptions() to correlate all test runs that are part of the same session.
     */
    testId?: string;

    /**
     * The device to emulate when launching the browser for all tests. Defaults to whatever you specify in your playwright.config.ts file
     * in the "use" option. See https://a.testable.io/remote-configurator for list of options.
     */
    deviceName?: string;

    /**
     * Emulate a custom device. Defaults to whatever you specify in your playwright.config.ts file
     * in the "use" option. See https://a.testable.io/remote-configurator for list of options.
     */
    device?: string;

    /**
     * Whether or not to capture a video of the browser session. Defaults to true.
     */
    recordVideo?: boolean;

    /**
     * Whether or not to capture performance metrics for each network request the browser makes. Defaults to true.
     */
    capturePerformance?: boolean;

    /**
     * If capturePerformance = true, then this setting controls whether or not to capture the request/response bodies for network requests.
     * Defaults to false.
     */
    captureBody?: boolean;

    /**
     *  Whether or not to capture any messages the page writes to the browser console. Defaults to true.
     */
    captureConsoleLog?: boolean;

    /**
     * Whether or not to log all commands sent at the CDP protocol level into the test log, disabled by default. Commands are also captured
     * and visible in your test results -> Command widget in an easy to read format.
     */
    logCommands?: boolean;

    /**
     * Whether or not to log all events generated by the CDP protocol into the test log, disabled by default. 
     */
    logEvents?: boolean;

    /**
     * The playwright module version to use on the remote end when launching the browser. Defaults to the version that corresponds to the 
     * browser version you chose. Example: 1.35.1.
     */
    playwrightVersion?: string;

    /**
     * If you choose to source the VMs from your own AWS account, you can choose the specific vpc (e.g. vpc-xxxxxx) in which to launch the EC2 instance.
     */
    vpc?: string;

    /**
     * If you choose to source the VMs from your own cloud account, you can choose the specific subnet in which to launch the VMs.
     */
    subnet?: string;

    /**
     * If you choose to source the VMs from your own AWS account, you can choose the specific keypair (e.g. vpc-xxxxxx) that will be associated with your EC2 instance.
     */
    keyPair?: string;

    /**
     * If you choose to source the VMs from your own Azure account, you can choose the specific resource group in which to launch the VM.
     */
    resourceGroup?: string;

    /**
     * If you choose to source the VMs from your own Azure or GCP account, you can choose the specific network in which to launch the VM.
     */
    network?: string;

    /**
     * If you choose to source the VMs from your own GCP account, you can choose the specific zone in which to launch the VM.
     */
    zone?: string;

    /**
     * For Testable Enterprise, update the server url to point at your Testable playwright endpoint or the coordinator endpoint at /playwright.
     * Defaults to wss://playwright.testable.io (Testable Cloud).
     */
    serverUrl?: string;
}

/**
 * @deprecated Use defineConfig(config, options) instead in your playwright.config.ts file. No changes per spec file
 * required in that case.
 * 
 * Create a Testable fixture to use in your Playwright test specs. Can you be used both when using Testable as a remote 
 * browser grid as well as when you want to upload and run your test on Testable test runners. See the README for more details.
 * 
 * All options can either be passed here or in your playwright.config.ts file at metadata: { testable: { ... options ... } }.
 * Values here override any value passed in your config file.
 * 
 * Remote example:
 * 
 * ```js
 * import { createFixture as createTestableFixture } from 'testable-playwright-test';
 * 
 * const test = createTestableFixture({
 *   // found at Org Management => API Keys, required for remote tests to work
 *   key: 'xxxxxxxx',
 *   screenResolution: '1920x1080',
 *   region: 'aws-us-east-1',
 *   testCaseName: 'Project Demo',
 *   reportId: `test-${Date.now()}`
 * });
 *
 * test('has title', async ({ page }) => {
 *   await page.goto('https://playwright.dev/');
 *   //...
 * });
 * ```
 * 
 *  * Upload to Testable example:
 * 
 * ```js
 * import { createFixture as createTestableFixture } from 'testable-playwright-test';
 * 
 * const test = createTestableFixture();
 *
 * test('has title', async ({ page }) => {
 *   await page.goto('https://playwright.dev/');
 *   //...
 * });
 * ```
 * 
 * @param options Required for remote tests, ignored for uploaded tests where all settings come from the scenario and test configuration.
 */
export function createFixture(options?: Options): playwrightTest.TestType<playwrightTest.PlaywrightTestArgs & playwrightTest.PlaywrightTestOptions, playwrightTest.PlaywrightWorkerArgs & playwrightTest.PlaywrightWorkerOptions>;

/**
 * A drop-in replacement for defineConfig() in the @playwright/test package.
 * 
 * Example:
 * 
 * ```ts
 * const { devices } = require('@playwright/test');
 * const { defineConfig } = require('testable-playwright-test');
 *
 * export default defineConfig({
 *   // your Playwright config contents here
 * }, {
 *   // mandatory api key (found under Org Management => API Keys)
 *   key: "[your-api-key]",
 *   // see https://a.testable.io/remote-configurator for all other options available
 *   testCaseName: 'My Playwright Tests',
 *   region: 'us-east-1',
 *   screenshot: 'afterFailed',
 *   tags: `test-${Date.now()}`
 * });
 * ```
 * 
 * @param config Playwright config
 * @param options Testable options related to using Testable Cloud or Enterprise as your remote browser grid
 */
export function defineConfig(config: playwrightTest.PlaywrightTestConfig, options?: Options): playwrightTest.PlaywrightTestConfig;