Конфигурация

Что вы узнаете

Где Testplane ищет конфигурационный файл
Как переопределить настройки без изменения конфигурационного файла
Как работает наследование настроек
Как настроить параллельный запуск тестов и тайм-ауты
Как подключить плагины

Введение

Testplane настраивается тремя способами: через конфигурационный файл, переменные окружения и аргументы командной строки.

Конфигурационный файл — основной источник настроек: в нём указывают браузеры, пути к тестам, параллельность, плагины и тайм-ауты. Переменные окружения и CLI-аргументы позволяют переопределить отдельные параметры без изменения файла, это удобно для CI/CD или локальных экспериментов.

Полный справочник параметров см. в документации по конфигурации.

Конфигурационный файл

При запуске Testplane ищет конфигурационный файл в текущей рабочей директории. Поддерживаются следующие имена файлов (в порядке приоритета):

.testplane.conf.ts
.testplane.conf.js
testplane.config.ts
testplane.config.js
testplane.config.cts
testplane.config.cjs

Если нужно использовать конфиг из другого места, укажите путь через опцию --config:

npx testplane --config ./configs/testplane.local.ts

Способы задания параметров

Параметры конфигурации Testplane можно задавать тремя способами:

Файл конфигурации: основной способ, подходит для большинства настроек
Переменные окружения: удобно для CI/CD и чувствительных данных
Аргументы CLI: для быстрого переопределения при запуске

Переопределение через переменные окружения

Любой параметр конфигурации можно переопределить через переменные окружения. Имя переменной формируется из имени параметра в конфиге:

Замените camelCase на snake_case (например, baseUrl → base_url)
Для вложенных параметров соедините все уровни через _
Добавьте префикс testplane_

# gridUrl в конфиге → testplane_grid_url
testplane_grid_url=local npx testplane

# browsers.firefox.headless в конфиге → testplane_browsers_firefox_headless
testplane_browsers_firefox_headless=false npx testplane

Переопределение через CLI

Параметры также можно переопределить через CLI-аргумент:

Замените camelCase на kebab-case (например, baseUrl → base-url)
Для вложенных параметров соедините все уровни через дефис
Добавьте -- в начале

# gridUrl в конфиге → --grid-url в CLI
npx testplane --grid-url local

# browsers.firefox.headless в конфиге → --browsers-firefox-headless в CLI
npx testplane --browsers-firefox-headless false

Приоритет параметров

При конфликте значений применяется следующий приоритет (от высшего к низшему):

Приоритет	Источник	Пример
1	CLI аргумент	`--base-url http://example.com`
2	Переменная окружения	`testplane_base_url=http://example.com`
3	Файл конфигурации	`baseUrl: "http://example.com"`
4	Значение по умолчанию	—

Наследование параметров

Testplane поддерживает каскадное наследование параметров: настройки, заданные на корневом уровне конфига, применяются ко всем браузерам. Браузеры могут переопределять эти значения.

Пример наследования

testplane.config.ts
import type { ConfigInput } from "testplane";

export default {
    // Корневые настройки — применяются ко всем браузерам
    baseUrl: "http://localhost:3000",
    retry: 2,
    sessionsPerBrowser: 3,
    browsers: {
        chrome: {
            // Наследует retry: 2 и sessionsPerBrowser: 3
            desiredCapabilities: {
                browserName: "chrome",
            },
        },
        firefox: {
            // Переопределяет retry, наследует sessionsPerBrowser: 3
            retry: 5,
            desiredCapabilities: {
                browserName: "firefox",
            },
        },
    },
    // ...
} satisfies ConfigInput;

В этом примере:

Chrome получит retry: 2 и sessionsPerBrowser: 3 (наследование)
Firefox получит retry: 5 (переопределение) и sessionsPerBrowser: 3 (наследование)

к сведению

Единственный параметр, который нельзя вынести на корневой уровень — это desiredCapabilities. Он должен быть задан для каждого браузера отдельно.

Базовые параметры

Ретраи (retry)

Параметр retry определяет, сколько раз Testplane будет перезапускать упавший тест.

testplane.config.ts
import type { ConfigInput } from "testplane";

export default {
    // Глобальное значение для всех браузеров
    retry: 2,
    browsers: {
        chrome: {
            // Для нестабильного браузера можно увеличить
            retry: 5,
            desiredCapabilities: { browserName: "chrome" },
        },
    },
    // ...
} satisfies ConfigInput;

Расположение тестовых файлов

Наборы тестовых файлов и браузеры для их запуска указываются в секции sets:

testplane.config.ts
import type { ConfigInput } from "testplane";

export default {
    sets: {
        desktop: {
            // Пути к тестам
            files: ["tests/desktop/**/*.test.ts"],
            browsers: ["chrome", "firefox"],
        },
        mobile: {
            files: ["tests/mobile/**/*.test.ts"],
            // Можно исключить файлы
            ignoreFiles: ["tests/mobile/**/*.skip.ts"],
            browsers: ["iphone", "android"],
        },
    },
    // ...
} satisfies ConfigInput;

Запуск конкретного сета:

npx testplane --set desktop

Подробнее о сетах см. в документации по sets.

Dev Server

Секция devServer позволяет автоматически запускать сервер разработки перед тестами:

testplane.config.ts
import type { ConfigInput } from "testplane";

const SERVER_PORT = 3000;

export default {
    devServer: {
        command: "npm run dev",
        env: { PORT: SERVER_PORT },
        reuseExisting: true,
        readinessProbe: {
            url: `http://localhost:${SERVER_PORT}/health`,
        },
    },
    baseUrl: "http://localhost:3000",
    // ...
} satisfies ConfigInput;

Testplane запустит команду и дождётся готовности сервера по указанному URL.

warning

Секция devServer только запускает сервер. Не забудьте также настроить baseUrl.

подсказка

При использовании reuseExisting: true обязательно укажите readinessProbe.url: Testplane проверит, запущен ли сервер, и не будет запускать новый.

Подробнее см. в документации по devServer.

Параллельность выполнения

Testplane запускает тесты параллельно, что значительно ускоряет прогон. Для настройки параллельности используются два основных параметра: sessionsPerBrowser и workers.

sessionsPerBrowser определяет максимальное число параллельных браузерных сессий для каждого браузера
workers определяет число воркер-процессов Node.js для параллельного выполнения тестов

testplane.config.ts
import type { ConfigInput } from "testplane";

export default {
    browsers: {
        chrome: {
            sessionsPerBrowser: 5,
            desiredCapabilities: {
                browserName: "chrome",
            },
        },
        firefox: {
            sessionsPerBrowser: 3,
            desiredCapabilities: {
                browserName: "firefox",
            },
        },
    },
    system: {
        workers: 4,
    },
    // ...
} satisfies ConfigInput;

В этом примере Testplane может запустить до 5 параллельных сессий Chrome и до 3 сессий Firefox, распределяя тесты между 4 воркер-процессами.

Тайм-ауты

Testplane позволяет настроить тайм-ауты для для контроля времени выполнения операций:

httpTimeout — тайм-аут HTTP-запросов к WebDriver
testTimeout — максимальное время выполнения одного теста
pageLoadTimeout — тайм-аут загрузки страницы в браузере
waitTimeout — тайм-аут для команд ожидания (waitFor*)

testplane.config.ts
import type { ConfigInput } from "testplane";

export default {
    // Глобальные тайм-ауты
    pageLoadTimeout: 20000,
    httpTimeout: 20000,
    testTimeout: 90000,
    browsers: {
        chrome: {
            // Тайм-ауты можно переопределить для конкретного браузера
            pageLoadTimeout: 30000,
            waitTimeout: 5000,
            desiredCapabilities: { browserName: "chrome" },
        },
    },
    // ...
} satisfies ConfigInput;

Полный список тайм-аутов и их описание см. в документации.

Подключение плагинов

Плагины подключаются и настраиваются в секции plugins в конфигурационном файле. Каждый ключ — это имя npm-пакета плагина, а значение — объект с его параметрами.

Пример с html-reporter

html-reporter — плагин для генерации HTML-отчётов о тестах.

Установка:

npm install html-reporter --save-dev

Подключение:

testplane.config.ts
import type { ConfigInput } from "testplane";

export default {
    plugins: {
        "html-reporter/testplane": {
            enabled: true,
            path: "testplane-report",
            defaultView: "all",
            diffMode: "3-up-scaled",
        },
    },
    // ...
} satisfies ConfigInput;

Параметры плагина можно переопределить через переменные окружения:

# Отключить плагин
html_reporter_enabled=false npx testplane

# Изменить путь к отчёту
html_reporter_path=./custom-report npx testplane

Аналогично можно передать параметры через командную строку:

# Изменить путь к отчёту
npx testplane --html-reporter-path=./custom-report

# Изменить режим отображения diff
npx testplane --html-reporter-diff_mode=only-diff

Если параметр указан в нескольких местах, применяется значение с наивысшим приоритетом:

CLI — высший приоритет
Переменные окружения
Конфигурационный файл — низший приоритет

Это позволяет гибко управлять поведением плагинов в CI/CD без изменения конфига.

Настройка дефолтов для команд

Testplane позволяет задать значения по умолчанию для параметров некоторых команд. Вместо того чтобы передавать одни и те же опции при каждом вызове, можно указать их один раз в конфигурации.

assertViewOpts

Настройки по умолчанию для скриншотного тестирования. Позволяют задать, какие элементы игнорировать, допустимую разницу в пикселях, задержку перед снимком и другие параметры сравнения скриншотов.

export default {
    assertViewOpts: {
        ignoreElements: [".ads", ".dynamic-banner"],
        ignoreDiffPixelCount: "0.5%",
    },
    // ...
};

Полный список параметров см. в документации assertView.

expectOpts

Настройки для асинхронных проверок с ожиданием.

export default {
    system: {
        expectOpts: {
            wait: 5000, // макс. время ожидания (мс)
            interval: 200, // интервал проверок (мс)
        },
    },
    // ...
};

Полный список параметров см. в документации по expect-матчерам.

stateOpts

Настройки для команд сохранения и восстановления состояния браузера. Определяют, что сохранять (cookies, localStorage, sessionStorage), куда сохранять, и нужно ли удалять файл после тестов.

export default {
    stateOpts: {
        path: "./tmp/auth-state.json",
        cookies: true,
        localStorage: true,
        sessionStorage: false,
    },
    // ...
};

Полный список параметров см. в документации по saveState и restoreState.

Конфигурация

Введение​

Конфигурационный файл​

Способы задания параметров​

Переопределение через переменные окружения​

Переопределение через CLI​

Приоритет параметров​

Наследование параметров​

Пример наследования​

Базовые параметры​

Ретраи (retry)​

Расположение тестовых файлов​

Dev Server​

Параллельность выполнения​

Тайм-ауты​

Подключение плагинов​

Пример с html-reporter​

Настройка дефолтов для команд​

assertViewOpts​

expectOpts​

stateOpts​