@tramvai/test-pw 3.4.1 → 3.4.6

package/README.md

@@ -6,50 +6,92 @@ Set of helpers for using [playwright](https://playwright.dev) in the integration
 
 ## Installation
 
-```bash
-npm i --save-dev @tramvai/test-pw
+```bash npm2yarn
+npm install --save-dev @tramvai/test-pw
 ```
 
-## How To
+## Usage
 
-### Tests in browser
+### Configuration
 
-`Playwright` runs tests in headless Chrome browser, documentation can be found on [official site](https://pptr.dev/)
+Create file `playwright.config.ts` with defaults from `@tramvai/test-pw` package:
+
+```ts title="playwright.config.ts"
+import { createPlaywrightConfig } from '@tramvai/test-pw';
+
+export default createPlaywrightConfig();
+```
+
+You can always extend default config, here is `createPlaywrightConfig` type definition:
 
 ```ts
-import { startCli } from '@tramvai/test-integration';
-import { initPlaywright, wrapPlaywrightPage } from '@tramvai/test-pw';
+// passed configuration object will be merged with defaults
+type createPlaywrightConfig = (config: PlaywrightTestConfig) => PlaywrightTestConfig;
+```
 
-beforeAll(async () => {
-  app = await startCli('bootstrap', {
-    env: {
-      SOME_ENV: 'test',
-    },
-  });
-}, 80000);
+### Testing
 
-afterAll(() => {
-  return app.close();
-});
+:::tip
+
+Use case for this section and `startAppFixture` - monorepo with many tramvai modules and example applications, where you need to test independent features.
+
+All usage of `startAppFixture` in different workers will run development build, which might not be optimal for tests execution time, if you want to test the same app in different cases.
+
+For real applications, prefer to run application once as [web server](https://playwright.dev/docs/test-webserver) or manually and pass `baseUrl` after.
 
-it('Playwright', async () => {
-  const { browser } = await initPlaywright(app.serverUrl);
+:::
 
-  const page = await browser.newPage();
-  const wrapper = wrapPlaywrightPage(page);
+`@tramvai/test-pw` provide a useful fixture for application start (local server in development mode) and testing - `startAppFixture`. This fixture use `startCli` method from [@tramvai/test-integration](references/tramvai/test/integration.md) package.
 
-  await page.goto(app.serverUrl);
+First, you need to add and configure this fixture for application tests:
 
-  expect(
-    await page.$eval('.application', (node) => (node as HTMLElement).innerText)
-  ).toMatchInlineSnapshot(`"Main Page click link"`);
+```ts title="__integration__/test-fixture.ts"
+import path from 'path';
+import { test as base } from '@playwright/test';
+import type { StartAppTypes } from '@tramvai/test-pw';
+import { startAppFixture } from '@tramvai/test-pw';
 
-  await wrapper.router.navigate('./second');
+type TestFixture = {};
 
-  expect(
-    await page.$eval('.application', (node) => (node as HTMLElement).innerText)
-  ).toMatchInlineSnapshot(`"Second Page click link"`);
+type WorkerFixture = {
+  app: StartAppTypes.TestApp;
+  appTarget: StartAppTypes.AppTarget;
+  startOptions: StartAppTypes.StartOptions;
+};
 
-  await browser.close();
+export const test = base.extend<TestFixture, WorkerFixture>({
+  appTarget: [
+    // provide application name and directory
+    {
+      target: 'appName',
+      cwd: path.resolve(__dirname, '..'),
+    },
+    { scope: 'worker', auto: true, option: true },
+  ],
+  // any `startCli` parameters
+  startOptions: [{
+    env: {
+      SOME_MOCKED_API: 'xxx'
+    },
+  }, { scope: 'worker', auto: true, option: true }],
+
+  app: startAppFixture,
+});
+```
+
+Then, use the `app` object in integration tests:
+
+```ts title="__integration__/appName.integration.ts"
+import { expect } from '@playwright/test';
+import { test } from './test-fixture';
+
+test.describe('examples/app', async () => {
+  test('Navigation is visible', async ({ app, page }) => {
+    await page.goto(app.serverUrl);
+
+    expect(page.getByRole('navigation')).toBeVisible();
+  });
 });
 ```
+
+You can find more info about `app` object in our [Testing Guide](guides/testing.md#integration-tests)

package/lib/config.d.ts

@@ -0,0 +1,3 @@
+import type { PlaywrightTestConfig } from '@playwright/test';
+export declare const createPlaywrightConfig: (userConfig?: Partial<PlaywrightTestConfig>) => PlaywrightTestConfig & Partial<PlaywrightTestConfig>;
+//# sourceMappingURL=config.d.ts.map

package/lib/config.es.js

@@ -0,0 +1,34 @@
+import mergeDeep from '@tinkoff/utils/object/mergeDeep';
+import { devices } from 'playwright-core';
+import envCi from 'env-ci';
+
+const ciInfo = envCi();
+const config = {
+    testDir: '.',
+    testMatch: /.*\.(integration)\.(js|ts)/,
+    fullyParallel: true,
+    retries: ciInfo.isCi ? 2 : 0,
+    workers: 1,
+    reporter: [['list'], ['html', { open: 'never' }]],
+    use: {
+        video: 'on-first-retry',
+        screenshot: 'only-on-failure',
+        trace: ciInfo.isCi ? 'retain-on-failure' : 'on',
+        launchOptions: {
+            executablePath: process.env.PLAYWRIGHT_EXECUTABLE_PATH,
+        },
+    },
+    projects: [
+        {
+            name: 'chromium',
+            use: {
+                ...devices['Desktop Chrome'],
+            },
+        },
+    ],
+};
+const createPlaywrightConfig = (userConfig = {}) => {
+    return mergeDeep({}, config, userConfig);
+};
+
+export { createPlaywrightConfig };

package/lib/config.js

@@ -0,0 +1,43 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var mergeDeep = require('@tinkoff/utils/object/mergeDeep');
+var playwrightCore = require('playwright-core');
+var envCi = require('env-ci');
+
+function _interopDefaultLegacy (e) { return e && typeof e === 'object' && 'default' in e ? e : { 'default': e }; }
+
+var mergeDeep__default = /*#__PURE__*/_interopDefaultLegacy(mergeDeep);
+var envCi__default = /*#__PURE__*/_interopDefaultLegacy(envCi);
+
+const ciInfo = envCi__default["default"]();
+const config = {
+    testDir: '.',
+    testMatch: /.*\.(integration)\.(js|ts)/,
+    fullyParallel: true,
+    retries: ciInfo.isCi ? 2 : 0,
+    workers: 1,
+    reporter: [['list'], ['html', { open: 'never' }]],
+    use: {
+        video: 'on-first-retry',
+        screenshot: 'only-on-failure',
+        trace: ciInfo.isCi ? 'retain-on-failure' : 'on',
+        launchOptions: {
+            executablePath: process.env.PLAYWRIGHT_EXECUTABLE_PATH,
+        },
+    },
+    projects: [
+        {
+            name: 'chromium',
+            use: {
+                ...playwrightCore.devices['Desktop Chrome'],
+            },
+        },
+    ],
+};
+const createPlaywrightConfig = (userConfig = {}) => {
+    return mergeDeep__default["default"]({}, config, userConfig);
+};
+
+exports.createPlaywrightConfig = createPlaywrightConfig;

package/lib/fixtures/start-app.d.ts

@@ -0,0 +1,33 @@
+import type { WorkerFixture } from '@playwright/test';
+import type { StartCliOptions, StartCliResult } from '@tramvai/test-integration';
+import type { ApplicationConfigEntry, ConvertToSchema } from '@tramvai/cli';
+export declare namespace StartAppTypes {
+    type TestApp = StartCliResult;
+    type AppTarget = {
+        name: string;
+        cwd: string;
+        config?: Partial<ConvertToSchema<ApplicationConfigEntry>>;
+    } | {
+        target: string;
+        cwd: string;
+        name?: string;
+    };
+    type StartOptions = StartCliOptions;
+}
+/**
+ * Фикстура запускает приложение с помощью метода `startCli` из `@tramvai/test-integration`
+ * @param appTarget указывает какое приложение запускать (может как указывать на существующее приложение с tramvai.json конфигом так и принимать полный конфиг)
+ * @param startOptions дополнительные параметры метода `startCli` (например env переменные для запущенного приложения)
+ * @returns возвращает свойства приложения (например адрес запущенного сервера на локалхосте) и удобные тестовые методы (например обертки над papi и superagent)
+ */
+export declare const startAppFixture: [
+    WorkerFixture<StartAppTypes.TestApp, {
+        appTarget: StartAppTypes.AppTarget;
+        startOptions: StartAppTypes.StartOptions;
+    }>,
+    {
+        scope: 'worker';
+        timeout: number;
+    }
+];
+//# sourceMappingURL=start-app.d.ts.map

package/lib/fixtures/start-app.es.js

@@ -0,0 +1,38 @@
+import mergeDeep from '@tinkoff/utils/object/mergeDeep';
+import path from 'path';
+import { startCli } from '@tramvai/test-integration';
+
+/**
+ * Фикстура запускает приложение с помощью метода `startCli` из `@tramvai/test-integration`
+ * @param appTarget указывает какое приложение запускать (может как указывать на существующее приложение с tramvai.json конфигом так и принимать полный конфиг)
+ * @param startOptions дополнительные параметры метода `startCli` (например env переменные для запущенного приложения)
+ * @returns возвращает свойства приложения (например адрес запущенного сервера на локалхосте) и удобные тестовые методы (например обертки над papi и superagent)
+ */
+const startAppFixture = [
+    async ({ appTarget, startOptions }, use) => {
+        var _a;
+        let app;
+        try {
+            app = await startCli('target' in appTarget
+                ? appTarget.target
+                : mergeDeep(appTarget.config, {
+                    name: appTarget.name,
+                    type: 'application',
+                    root: appTarget.cwd,
+                }), {
+                ...startOptions,
+                rootDir: (_a = appTarget.cwd) !== null && _a !== void 0 ? _a : path.dirname(path.resolve(module.parent.filename, '.')),
+            });
+            await use(app);
+            await app.close();
+        }
+        catch (error) {
+            console.error(`startApp fixture failed:`, error);
+            await (app === null || app === void 0 ? void 0 : app.close());
+            throw error;
+        }
+    },
+    { scope: 'worker', timeout: 60000 },
+];
+
+export { startAppFixture };

package/lib/fixtures/start-app.js

@@ -0,0 +1,47 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var mergeDeep = require('@tinkoff/utils/object/mergeDeep');
+var path = require('path');
+var testIntegration = require('@tramvai/test-integration');
+
+function _interopDefaultLegacy (e) { return e && typeof e === 'object' && 'default' in e ? e : { 'default': e }; }
+
+var mergeDeep__default = /*#__PURE__*/_interopDefaultLegacy(mergeDeep);
+var path__default = /*#__PURE__*/_interopDefaultLegacy(path);
+
+/**
+ * Фикстура запускает приложение с помощью метода `startCli` из `@tramvai/test-integration`
+ * @param appTarget указывает какое приложение запускать (может как указывать на существующее приложение с tramvai.json конфигом так и принимать полный конфиг)
+ * @param startOptions дополнительные параметры метода `startCli` (например env переменные для запущенного приложения)
+ * @returns возвращает свойства приложения (например адрес запущенного сервера на локалхосте) и удобные тестовые методы (например обертки над papi и superagent)
+ */
+const startAppFixture = [
+    async ({ appTarget, startOptions }, use) => {
+        var _a;
+        let app;
+        try {
+            app = await testIntegration.startCli('target' in appTarget
+                ? appTarget.target
+                : mergeDeep__default["default"](appTarget.config, {
+                    name: appTarget.name,
+                    type: 'application',
+                    root: appTarget.cwd,
+                }), {
+                ...startOptions,
+                rootDir: (_a = appTarget.cwd) !== null && _a !== void 0 ? _a : path__default["default"].dirname(path__default["default"].resolve(module.parent.filename, '.')),
+            });
+            await use(app);
+            await app.close();
+        }
+        catch (error) {
+            console.error(`startApp fixture failed:`, error);
+            await (app === null || app === void 0 ? void 0 : app.close());
+            throw error;
+        }
+    },
+    { scope: 'worker', timeout: 60000 },
+];
+
+exports.startAppFixture = startAppFixture;

package/lib/index.d.ts

@@ -3,4 +3,6 @@ export * from './constants';
 export { initPlaywright } from './launch';
 export { wrapPlaywrightPage } from './wrapper';
 export * from './utils';
+export { createPlaywrightConfig } from './config';
+export { startAppFixture, StartAppTypes } from './fixtures/start-app';
 //# sourceMappingURL=index.d.ts.map

package/lib/index.es.js

@@ -3,3 +3,5 @@ export { PLAYWRIGHT_DEFAULT_LAUNCH_OPTIONS } from './constants.es.js';
 export { initPlaywright } from './launch.es.js';
 export { wrapPlaywrightPage } from './wrapper.es.js';
 export { waitHydrated } from './utils.es.js';
+export { createPlaywrightConfig } from './config.es.js';
+export { startAppFixture } from './fixtures/start-app.es.js';

package/lib/index.js

@@ -7,6 +7,8 @@ var constants = require('./constants.js');
 var launch = require('./launch.js');
 var wrapper = require('./wrapper.js');
 var utils = require('./utils.js');
+var config = require('./config.js');
+var startApp = require('./fixtures/start-app.js');
 
 
 
@@ -14,6 +16,8 @@ exports.PLAYWRIGHT_DEFAULT_LAUNCH_OPTIONS = constants.PLAYWRIGHT_DEFAULT_LAUNCH_
 exports.initPlaywright = launch.initPlaywright;
 exports.wrapPlaywrightPage = wrapper.wrapPlaywrightPage;
 exports.waitHydrated = utils.waitHydrated;
+exports.createPlaywrightConfig = config.createPlaywrightConfig;
+exports.startAppFixture = startApp.startAppFixture;
 Object.keys(playwrightCore).forEach(function (k) {
 	if (k !== 'default' && !exports.hasOwnProperty(k)) Object.defineProperty(exports, k, {
 		enumerable: true,

package/lib/launch.d.ts

@@ -4,6 +4,9 @@ type PWOptions = Parameters<typeof chromium.launch>[0];
 type Options = PWOptions & {
     enableLogging?: boolean;
 };
+/**
+ * @deprecated - use Playwright directly or with `startAppFixture`
+ */
 export declare const initPlaywright: (serverUrl: string, { enableLogging, ...options }?: Options) => Promise<{
     browser: Browser;
     getPageWrapper: (url?: string) => Promise<{

package/lib/launch.es.js

@@ -19,6 +19,9 @@ const enableBrowserLogger = async ({ browser, serverUrl, }) => {
     });
     await page.close();
 };
+/**
+ * @deprecated - use Playwright directly or with `startAppFixture`
+ */
 const initPlaywright = async (serverUrl, { enableLogging = true, ...options } = {}) => {
     const browser = await chromium.launch({
         ...PLAYWRIGHT_DEFAULT_LAUNCH_OPTIONS,

package/lib/launch.js

@@ -23,6 +23,9 @@ const enableBrowserLogger = async ({ browser, serverUrl, }) => {
     });
     await page.close();
 };
+/**
+ * @deprecated - use Playwright directly or with `startAppFixture`
+ */
 const initPlaywright = async (serverUrl, { enableLogging = true, ...options } = {}) => {
     const browser = await playwrightCore.chromium.launch({
         ...constants.PLAYWRIGHT_DEFAULT_LAUNCH_OPTIONS,

package/lib/wrapper.d.ts

@@ -2,6 +2,9 @@ import type { Page } from 'playwright-core';
 declare global {
     var nativeConsole: typeof console;
 }
+/**
+ * @deprecated - use Playwright directly or with `startAppFixture`
+ */
 export declare const wrapPlaywrightPage: (page: Page) => {
     page: Page;
     reset: (url?: string) => Promise<import("playwright-core").Response | null>;

package/lib/wrapper.es.js

@@ -14,6 +14,9 @@ const checkSsrErrors = (text) => {
 };
 const format = consoleWithStyle((stderr && stderr.level) || 0);
 const { nativeConsole } = global;
+/**
+ * @deprecated - use Playwright directly or with `startAppFixture`
+ */
 const wrapPlaywrightPage = (page) => {
     if (page.url() && page.url() !== 'about:blank') {
         throw new Error(`You should wrap blank page before navigation, but page already has url "${page.url()}"`);

package/lib/wrapper.js

@@ -22,6 +22,9 @@ const checkSsrErrors = (text) => {
 };
 const format = consoleWithStyle__default["default"]((supportsColor.stderr && supportsColor.stderr.level) || 0);
 const { nativeConsole } = global;
+/**
+ * @deprecated - use Playwright directly or with `startAppFixture`
+ */
 const wrapPlaywrightPage = (page) => {
     if (page.url() && page.url() !== 'about:blank') {
         throw new Error(`You should wrap blank page before navigation, but page already has url "${page.url()}"`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tramvai/test-pw",
-  "version": "3.4.1",
+  "version": "3.4.6",
   "description": "",
   "main": "lib/index.js",
   "typings": "lib/index.d.ts",
@@ -18,10 +18,11 @@
   },
   "dependencies": {
     "@tinkoff/utils": "^2.1.2",
-    "@tramvai/test-integration": "3.4.1",
-    "@tramvai/tokens-router": "3.4.1",
+    "@tramvai/test-integration": "3.4.6",
+    "@tramvai/tokens-router": "3.4.6",
     "console-with-style": "^1.1.0",
     "supports-color": "8.1.1",
+    "env-ci": "^5.0.2",
     "tslib": "^2.4.0"
   },
   "peerDependencies": {
@@ -29,6 +30,9 @@
   },
   "devDependencies": {
     "@types/supports-color": "^8.1.1",
+    "@types/env-ci": "^3.1.0",
+    "@tramvai/cli": "3.4.6",
+    "@playwright/test": "1.29.0",
     "playwright-core": "1.29.0"
   },
   "license": "Apache-2.0",