@telefonica/acceptance-testing 4.0.0 → 5.0.0-beta1

package/README.md

@@ -51,13 +51,15 @@ If you want to autostart a server before running the acceptance tests, you can c
 }
 ```
 
-Additionally, you can include path and protocol parameters, that will be used to check if the server is ready:
+Additionally, you can include `host`, `protocol` and `path` parameters. The path will be used to check if the
+server is ready:
 
 ```json
 {
   "acceptanceTests": {
     "ciServer": {
       "command": "yarn dev",
+      "host": "127.0.0.1",
       "port": 3000,
       "path": "api/health",
       "protocol": "https"
@@ -66,6 +68,13 @@ Additionally, you can include path and protocol parameters, that will be used to
 }
 ```
 
+The `command` can be overridden by setting the `ACCEPTANCE_TESTING_SERVER_COMMAND` environment variable. For
+example:
+
+```sh
+ACCEPTANCE_TESTING_SERVER_COMMAND="yarn start" yarn test-acceptance
+```
+
 #### `protocol`
 
 Type: `string`, (`https`, `http`, `tcp`, `socket`) defaults to `tcp` or `http` if `path` is set.
@@ -200,7 +209,10 @@ test('example screenshot test', async () => {
 });
 ```
 
-`createApiEndpointMock` automatically mocks CORS response headers and preflight (`OPTIONS`) requests for you.
+- `createApiEndpointMock` automatically mocks CORS response headers and preflight (`OPTIONS`) requests for
+  you.
+- Both `interceptRequest` and `createApiEndpointMock` return a jest
+  [mock function](https://jestjs.io/docs/mock-function-api/#reference).
 
 ### Using globs
 
@@ -251,7 +263,8 @@ await elementHandle.uploadFile(prepareFile('/path/to/file'));
 
 ## Collecting coverage
 
-Set the `COLLECT_ACCEPTANCE_COVERAGE` environment variable to enable coverage collection.
+Set the `ACCEPTANCE_TESTING_COLLECT_COVERAGE` environment variable to enable coverage collection or run with
+the `--coverage` flag.
 
 The code must be instrumented with [nyc](https://github.com/istanbuljs/nyc/blob/main/docs/instrument.md),
 [babel-plugin-istanbul](https://github.com/istanbuljs/babel-plugin-istanbul) or any
@@ -323,6 +336,9 @@ page.on('pageerror', (err) => {
 });
 ```
 
+Page errors can be ignored by setting the `ACCEPTANCE_TESTING_IGNORE_PAGE_ERRORS` environment variable. Do not
+enable this by default as it could hide legitimate errors in your tests.
+
 ### Executing with --ui fails (Linux)
 
 If your desktop environment uses Wayland, you may see the following error when running the tests with the
@@ -347,3 +363,9 @@ To workaround this issue, you can install a newer Chrome in the repo where you a
 
 Note that this browser will only be used when running the tests with the `--ui` flag. In headless mode, the
 dockerized chromium will be used.
+
+### Debug mode
+
+If you need additional logs to debug the `acceptance-testing` library, you can set the
+`ACCEPTANCE_TESTING_DEBUG` environment variable or run the `acceptance-testing` command with the `--debug`
+flag.

package/dist/config.d.ts

@@ -0,0 +1,22 @@
+type Config = {
+    debug: boolean;
+    isCi: boolean;
+    isHeadless: boolean;
+    isLocal: boolean;
+    coveragePath: string;
+    coverageUrls: string[];
+    collectCoverage: boolean;
+    /** complete list of server options: https://www.npmjs.com/package/jest-dev-server */
+    server: {
+        command: string;
+        host?: string;
+        port?: number;
+        path?: string;
+        usedPortAction?: 'error' | 'ignore';
+        launchTimeout?: number;
+        protocol?: 'http' | 'tcp';
+        debug?: boolean;
+    };
+};
+export declare const getConfig: () => Config;
+export {};

package/dist/config.js

@@ -0,0 +1,57 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getConfig = void 0;
+const find_root_1 = __importDefault(require("find-root"));
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const IS_CI = !!process.env.CI || process.argv.includes('--ci');
+const IS_DEBUG = !!process.env.ACCEPTANCE_TESTING_DEBUG || process.argv.includes('--debug');
+const DEFAULT_CONFIG = {
+    debug: IS_DEBUG,
+    isCi: IS_CI,
+    isLocal: !IS_CI,
+    isHeadless: !!process.env.HEADLESS,
+    coveragePath: 'reports/coverage-acceptance',
+    collectCoverage: !!process.env.ACCEPTANCE_TESTING_COLLECT_COVERAGE || process.argv.includes('--coverage'),
+    coverageUrls: [],
+    server: {
+        debug: IS_DEBUG,
+        command: 'tail -f /dev/null',
+        host: '127.0.0.1',
+        usedPortAction: IS_CI ? 'error' : 'ignore', // In dev, if port is already taken, assume server is already running.
+        launchTimeout: 60000,
+    },
+};
+const PACKAGE_JSON_CONFIG = (() => {
+    const rootDir = (0, find_root_1.default)(process.cwd());
+    const packageJson = JSON.parse(fs_1.default.readFileSync(path_1.default.join(rootDir, 'package.json'), 'utf-8'));
+    const acceptanceTestsConfig = packageJson.acceptanceTests || {};
+    const server = (IS_CI ? acceptanceTestsConfig.ciServer : acceptanceTestsConfig.devServer) ||
+        acceptanceTestsConfig.server;
+    // not needed in the final config
+    delete acceptanceTestsConfig.ciServer;
+    delete acceptanceTestsConfig.devServer;
+    return {
+        ...acceptanceTestsConfig,
+        server,
+    };
+})();
+const CONFIG = (() => {
+    const config = {
+        ...DEFAULT_CONFIG,
+        ...PACKAGE_JSON_CONFIG,
+        server: {
+            ...DEFAULT_CONFIG.server,
+            ...PACKAGE_JSON_CONFIG.server,
+        },
+    };
+    config.server.protocol = config.server.path ? 'http' : 'tcp';
+    // overrides
+    config.server.command = process.env.ACCEPTANCE_TESTING_SERVER_COMMAND || config.server.command;
+    return config;
+})();
+const getConfig = () => CONFIG;
+exports.getConfig = getConfig;

package/dist/constants.d.ts

@@ -0,0 +1 @@
+export declare const LINUX_DOCKER_HOST_IP = "172.17.0.1";

package/dist/constants.js

@@ -0,0 +1,4 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LINUX_DOCKER_HOST_IP = void 0;
+exports.LINUX_DOCKER_HOST_IP = '172.17.0.1';

package/dist/coverage.d.ts

@@ -1,15 +1,15 @@
-export declare const getRootPath: () => any;
-/**
- * Assumes the code was instrumented with istanbul/nyc and the coverage report stored in `window.__coverage__`.
- * If not, this function does nothing.
- */
-export declare const collectFrontendCoverage: ({ coveragePath }: {
-    coveragePath: string;
-}) => Promise<void>;
-/**
- * Collects backend coverage reports from the provided URLs and stores them in the coverage folder
- */
-export declare const collectBackendCoverage: ({ coveragePath, coverageUrls, }: {
-    coveragePath: string;
-    coverageUrls: Array<string>;
-}) => Promise<void>;
+export declare const getRootPath: () => any;
+/**
+ * Assumes the code was instrumented with istanbul/nyc and the coverage report stored in `window.__coverage__`.
+ * If not, this function does nothing.
+ */
+export declare const collectFrontendCoverage: ({ coveragePath }: {
+    coveragePath: string;
+}) => Promise<void>;
+/**
+ * Collects backend coverage reports from the provided URLs and stores them in the coverage folder
+ */
+export declare const collectBackendCoverage: ({ coveragePath, coverageUrls, }: {
+    coveragePath: string;
+    coverageUrls: Array<string>;
+}) => Promise<void>;

package/dist/coverage.js

@@ -0,0 +1,119 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.collectBackendCoverage = exports.collectFrontendCoverage = exports.getRootPath = void 0;
+const path_1 = __importDefault(require("path"));
+const fs_1 = __importDefault(require("fs"));
+const utils_1 = require("./utils");
+const istanbul_lib_coverage_1 = __importDefault(require("istanbul-lib-coverage"));
+const getGlobalPage = () => global.page;
+const getRootPath = () => {
+    const rootPath = expect.getState().snapshotState._rootDir;
+    if (!rootPath) {
+        throw new Error('Root path not found');
+    }
+    return rootPath;
+};
+exports.getRootPath = getRootPath;
+/**
+ * We want to clear coverage files from previous runs, but at this point it is not easy because each
+ * worker runs a different instance of this script, so we can't just clear the coverage folder at
+ * the beginning of the test run.
+ *
+ * The solution is to remove the coverage folder when the stored ppid (parent process id) is
+ * different from the current one
+ */
+const prepareCoverageReportPath = ({ coveragePath }) => {
+    const ppidFile = path_1.default.join(coveragePath, '.ppid');
+    const nycOutputPath = path_1.default.join(coveragePath, '.nyc_output');
+    const ppid = process.ppid.toString();
+    if (!fs_1.default.existsSync(ppidFile) || fs_1.default.readFileSync(ppidFile, 'utf-8') !== ppid) {
+        // the condition is just to make sure we don't remove files outside the repo
+        if ((0, exports.getRootPath)() === process.cwd() && path_1.default.normalize(coveragePath).startsWith(process.cwd())) {
+            fs_1.default.rmSync(nycOutputPath, { recursive: true, force: true });
+        }
+        fs_1.default.mkdirSync(nycOutputPath, { recursive: true });
+        fs_1.default.writeFileSync(ppidFile, ppid);
+    }
+};
+const workerId = process.env.JEST_WORKER_ID || '0';
+/**
+ * Writes the coverage reports into single files, one per each coverage object (path). This makes it easier to merge them.
+ * The `workerId` from jest is used to avoid race conditions when multiple workers are running in parallel.
+ */
+const writeCombinedCoverage = (nycOutputPath, coverage) => {
+    Object.values(coverage).forEach((value) => {
+        if (value && value.path && value.hash) {
+            const filename = path_1.default.join(nycOutputPath, `${value.hash}-${workerId}.json`);
+            const currentCoverage = { [value.path]: value };
+            const previousCoverage = fs_1.default.existsSync(filename)
+                ? JSON.parse(fs_1.default.readFileSync(filename, 'utf8'))
+                : {};
+            const mergedCoverage = istanbul_lib_coverage_1.default.createCoverageMap(previousCoverage);
+            mergedCoverage.merge(currentCoverage);
+            (0, utils_1.debug)('Writing merged coverage:', value.path, value.hash);
+            fs_1.default.writeFileSync(filename, JSON.stringify(mergedCoverage.toJSON(), null, 2));
+        }
+        else {
+            (0, utils_1.debug)('Skip write coverage. Missing path or hash:', value);
+        }
+    });
+};
+/**
+ * Assumes the code was instrumented with istanbul/nyc and the coverage report stored in `window.__coverage__`.
+ * If not, this function does nothing.
+ */
+const collectFrontendCoverage = async ({ coveragePath }) => {
+    const nycOutputPath = path_1.default.join(coveragePath, '.nyc_output');
+    const coverage = await getGlobalPage().evaluate(() => {
+        return window.__coverage__;
+    });
+    if (!coverage) {
+        (0, utils_1.debug)('Skipping coverage collection. No coverage found.');
+        return;
+    }
+    (0, utils_1.debug)('Frontend coverage found');
+    prepareCoverageReportPath({ coveragePath });
+    fs_1.default.mkdirSync(nycOutputPath, { recursive: true });
+    writeCombinedCoverage(nycOutputPath, coverage);
+};
+exports.collectFrontendCoverage = collectFrontendCoverage;
+const writeCoverage = (nycOutputPath, nameSuffix, coverage) => {
+    Object.values(coverage).forEach((value) => {
+        if (value && value.path && value.hash) {
+            const filename = path_1.default.join(nycOutputPath, `${value.hash}${nameSuffix}.json`);
+            (0, utils_1.debug)('Writing coverage:', value.path, value.hash);
+            fs_1.default.writeFileSync(filename, JSON.stringify({ [value.path]: value }, null, 2));
+        }
+        else {
+            (0, utils_1.debug)('Skip write coverage. Missing path or hash:', value);
+        }
+    });
+};
+/**
+ * Collects backend coverage reports from the provided URLs and stores them in the coverage folder
+ */
+const collectBackendCoverage = async ({ coveragePath, coverageUrls, }) => {
+    const nycOutputPath = path_1.default.join(coveragePath, '.nyc_output');
+    (0, utils_1.debug)('Collecting backend coverage reports', coverageUrls);
+    const serverReports = await Promise.all(coverageUrls.map((url) => fetch(url)
+        .then((res) => {
+        if (res.ok &&
+            res.status === 200 &&
+            res.headers.get('content-type')?.includes('application/json')) {
+            return res.json();
+        }
+        (0, utils_1.debug)('Error fetching coverage report:', { url, status: res.status });
+        return null;
+    })
+        .catch(() => {
+        (0, utils_1.debug)('Error fetching coverage report:', { url });
+        return null;
+    })));
+    serverReports.forEach((report, index) => {
+        writeCoverage(nycOutputPath, `-backend${index}`, report.coverage);
+    });
+};
+exports.collectBackendCoverage = collectBackendCoverage;

package/dist/index.d.ts

@@ -1,91 +1,86 @@
-/// <reference types="node" />
-/// <reference types="jest" />
-/// <reference types="jest-image-snapshot" />
-import type { Browser, ClickOptions, ElementHandle, HTTPRequest, Page, ResponseForRequest, ScreenshotOptions, Viewport } from 'puppeteer';
-declare type CustomScreenshotOptions = ScreenshotOptions & {
-    skipNetworkWait?: boolean;
-};
-export declare const getGlobalBrowser: () => Browser;
-export declare const getGlobalPage: () => Page;
-export declare const serverHostName: string;
-export declare const serverPort: any;
-export interface PageApi extends Omit<Page, 'click' | 'type' | 'select'> {
-    clear: (selector: ElementHandle) => Promise<void>;
-    type: (selector: ElementHandle, text: string, options?: {
-        delay: number;
-    }) => Promise<void>;
-    click: (selector: ElementHandle, options?: ClickOptions) => Promise<void>;
-    select: (selector: ElementHandle, ...values: string[]) => Promise<string[]>;
-    screenshot: (options?: CustomScreenshotOptions) => Promise<Buffer | string | void>;
-}
-export declare const getPageApi: (page: Page) => PageApi;
-declare type RequestMatcherFn = (req: HTTPRequest) => boolean;
-export declare const interceptRequest: (matcher: RequestMatcherFn) => jest.Mock<Partial<ResponseForRequest>, [HTTPRequest]>;
-declare type ApiEndpointMock = {
-    spyOn(path: string, method?: string): jest.Mock<unknown, [HTTPRequest]>;
-};
-export declare const createApiEndpointMock: ({ origin, baseUrl, }?: {
-    origin?: string | undefined;
-    /** @deprecated use origin */
-    baseUrl?: string | undefined;
-}) => ApiEndpointMock;
-declare type CookieConfig = {
-    name: string;
-    value: string;
-    url?: string;
-    domain?: string;
-    path?: string;
-    secure?: boolean;
-    httpOnly?: boolean;
-    sameSite?: 'Strict' | 'Lax' | 'None';
-    expires?: number;
-    priority?: 'Low' | 'Medium' | 'High';
-    sameParty?: boolean;
-    sourceScheme?: 'Unset' | 'NonSecure' | 'Secure';
-    sourcePort?: number;
-};
-export interface TestViewport extends Viewport {
-    safeAreaInset?: {
-        top?: number | string;
-        right?: number | string;
-        bottom?: number | string;
-        left?: number | string;
-    };
-}
-interface OpenPageCommonConfig {
-    userAgent?: string;
-    viewport?: TestViewport;
-    isDarkMode?: boolean;
-    cookies?: Array<CookieConfig>;
-}
-interface OpenPageUrlConfig extends OpenPageCommonConfig {
-    url: string;
-}
-interface OpenPagePathConfig extends OpenPageCommonConfig {
-    url?: undefined;
-    path?: string;
-    port?: number;
-    protocol?: string;
-    hostname?: string;
-}
-declare type OpenPageConfig = OpenPageUrlConfig | OpenPagePathConfig;
-export declare const openPage: ({ userAgent, isDarkMode, viewport, cookies, ...urlConfig }: OpenPageConfig) => Promise<PageApi>;
-export declare const getScreen: (page: Page) => import("pptr-testing-library/dist/typedefs").IQueryUtils & import("pptr-testing-library/dist/typedefs").IScopedQueryUtils;
-export declare const screen: import("pptr-testing-library/dist/typedefs").IQueryUtils & import("pptr-testing-library/dist/typedefs").IScopedQueryUtils;
-export declare const within: (element: ElementHandle) => import("pptr-testing-library/dist/typedefs").IQueryUtils & import("pptr-testing-library/dist/typedefs").IScopedQueryUtils;
-export type { ElementHandle, Viewport } from 'puppeteer';
-/**
- * Returns a new path to the file that can be used by chromium in acceptance tests
- *
- * To be able to use `element.uploadFile()` in a dockerized chromium, the file must exist in the
- * host and the docker, and both sides must use the same path.
- *
- * To workaround this bug or limitation, this function prepares the file by copying it to /tmp in
- * the host and the container.
- */
-export declare const prepareFile: (filepath: string) => string;
-/**
- * A convenience method to defer an expectation
- */
-export declare const wait: <T>(expectation: () => T | Promise<T>, timeout?: number, interval?: number) => Promise<T>;
-export declare const waitForElementToBeRemoved: (element: ElementHandle<Element>, timeout?: number, interval?: number) => Promise<void>;
+import type { Browser, ClickOptions, ElementHandle, HTTPRequest, Page, ResponseForRequest, ScreenshotOptions, Viewport } from 'puppeteer';
+type CustomScreenshotOptions = ScreenshotOptions & {
+    skipNetworkWait?: boolean;
+};
+export declare const getGlobalBrowser: () => Browser;
+export declare const getGlobalPage: () => Page;
+export declare const serverHostName: string;
+export declare const serverPort: number | undefined;
+export interface PageApi extends Omit<Page, 'click' | 'type' | 'select'> {
+    clear: (selector: ElementHandle) => Promise<void>;
+    type: (selector: ElementHandle, text: string, options?: {
+        delay: number;
+    }) => Promise<void>;
+    click: (selector: ElementHandle, options?: ClickOptions) => Promise<void>;
+    select: (selector: ElementHandle, ...values: string[]) => Promise<string[]>;
+    screenshot: (options?: CustomScreenshotOptions) => Promise<Buffer | string | void>;
+}
+export declare const getPageApi: (page: Page) => PageApi;
+type RequestMatcherFn = (req: HTTPRequest) => boolean;
+export declare const interceptRequest: (matcher: RequestMatcherFn) => jest.Mock<Partial<ResponseForRequest> | Promise<Partial<ResponseForRequest>>, [HTTPRequest]>;
+type ApiEndpointMock = {
+    spyOn<T = any>(path: string, method?: string): jest.Mock<T, [HTTPRequest]>;
+};
+export declare const createApiEndpointMock: ({ origin }?: {
+    origin?: string;
+}) => ApiEndpointMock;
+type CookieConfig = {
+    name: string;
+    value: string;
+    url?: string;
+    domain?: string;
+    path?: string;
+    secure?: boolean;
+    httpOnly?: boolean;
+    sameSite?: 'Strict' | 'Lax' | 'None';
+    expires?: number;
+    priority?: 'Low' | 'Medium' | 'High';
+    sameParty?: boolean;
+    sourceScheme?: 'Unset' | 'NonSecure' | 'Secure';
+    sourcePort?: number;
+};
+export interface TestViewport extends Viewport {
+    safeAreaInset?: {
+        top?: number | string;
+        right?: number | string;
+        bottom?: number | string;
+        left?: number | string;
+    };
+}
+interface OpenPageCommonConfig {
+    userAgent?: string;
+    viewport?: TestViewport;
+    isDarkMode?: boolean;
+    cookies?: Array<CookieConfig>;
+}
+interface OpenPageUrlConfig extends OpenPageCommonConfig {
+    url: string;
+}
+interface OpenPagePathConfig extends OpenPageCommonConfig {
+    url?: undefined;
+    path?: string;
+    port?: number;
+    protocol?: string;
+    hostname?: string;
+}
+type OpenPageConfig = OpenPageUrlConfig | OpenPagePathConfig;
+export declare const openPage: ({ userAgent, isDarkMode, viewport, cookies, ...urlConfig }: OpenPageConfig) => Promise<PageApi>;
+export declare const getScreen: (page: Page) => import("pptr-testing-library/dist/typedefs").IQueryUtils & import("pptr-testing-library/dist/typedefs").IScopedQueryUtils;
+export declare const screen: import("pptr-testing-library/dist/typedefs").IQueryUtils & import("pptr-testing-library/dist/typedefs").IScopedQueryUtils;
+export declare const within: (element: ElementHandle) => import("pptr-testing-library/dist/typedefs").IQueryUtils & import("pptr-testing-library/dist/typedefs").IScopedQueryUtils;
+export type { ElementHandle, Viewport } from 'puppeteer';
+/**
+ * Returns a new path to the file that can be used by chromium in acceptance tests
+ *
+ * To be able to use `element.uploadFile()` in a dockerized chromium, the file must exist in the
+ * host and the docker, and both sides must use the same path.
+ *
+ * To workaround this bug or limitation, this function prepares the file by copying it to /tmp in
+ * the host and the container.
+ */
+export declare const prepareFile: (filepath: string) => string;
+/**
+ * A convenience method to defer an expectation
+ */
+export declare const wait: <T>(expectation: () => Promise<T> | T, timeout?: number, interval?: number) => Promise<T>;
+export declare const waitForElementToBeRemoved: (element: ElementHandle<Element>, timeout?: number, interval?: number) => Promise<void>;