Перейти к основному содержимому

Testplane v8 → v9

Что изменилось?​

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

Руководство по миграции​

1. Проверьте системные требования и обновите Testplane​

Для Testplane 9 нужен Node 22 или новее. Мы рекомендуем использовать актуальную версию 22.x или выше, но минимально необходимая версия — 22.12.

Установите Testplane 9:

npm install -D testplane@9

2. Проверьте изменения в визуальных проверках​

Примите изменившиеся скриншоты assertView​

В Testplane 9 существенно изменилась логика работы assertView: визуальные проверки стали надежнее, а снятые скриншоты — корректнее.

При обновлении на Testplane 9 изменится примерно 5% скриншотов assertView. Чаще всего достаточно просто принять все изменившиеся эталоны. Для этого можно:

  • Использовать HTML Reporter и принять изменения после ревью (рекомендуется)
  • Запустить testplane --update-refs, чтобы обновить все эталоны

Если вы заметили нежелательные изменения в скриншотах, посмотрите раздел Типовые проблемы ниже. Если там нет подходящего решения, напишите нам в github issues или community чат в Telegram.

Опция selectorToScroll устарела​

В Testplane 9 assertView автоматически определяет элемент, который нужно скроллить, поэтому передавать этот селектор вручную больше не нужно и не рекомендуется.

Опция selectorToScroll все еще поддерживается, но после миграции нескольких крупных проектов на Testplane 9 мы не нашли ни одного случая, где она действительно была бы полезна. Если же передать некорректный селектор, это только навредит.

Теперь можно снимать скриншоты псевдоэлементов​

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

await browser.assertView("menu-highlight", "[data-testid=menu]::after");

Один из частых сценариев — скриншоты подсветок фона, которые появляются вокруг элементов списка или меню при наведении.

Теперь скриншоты можно обрезать через cropMargins​

Если раньше вы использовали хаки для обрезки скриншотов, например чтобы убрать скроллбары на Android-эмуляторах, теперь это можно сделать нативно.

Например, чтобы обрезать скроллбар на Android-эмуляторах, можно сделать так:

testplane.config.js
export default {
    browsers: {
        browserName: "android-webview",
        platformName: "android",
        assertViewOpts: {
            cropMargins: { right: 16 },
        },
    },
};

3. Обновите работу с глобальными объектами в TypeScript​

Testplane 9 больше не добавляет it, describe и другие глобальные объекты в глобальное пространство типов.

Если вы хотите оставить прежнее поведение​

Установите небольшой пакет с глобальными типами:

npm install -D @testplane/globals

Затем добавьте его в tsconfig.json:

{
    "compilerOptions": {
        "types": ["@testplane/globals"]
    }
}

Удалите testplane из массива types, если он был там раньше.

Либо используйте triple-slash directive в любом из ваших TS файлов: /// <reference types="@testplane/globals" />.

Если вы предпочитаете явные импорты​

Можно импортировать глобальные объекты явно:

import { it, describe } from "testplane";

describe("my test", () => {
    it("should do something", () => {
        /* ... */
    });
});

4. Не используйте automationProtocol: "devtools"​

Testplane 9 больше не поддерживает значение "devtools" для опции automationProtocol. Этот режим долго был источником разных проблем, а для всех его возможностей сейчас есть более удачные альтернативы:

  • Для запуска Testplane с локальными браузерами используйте gridUrl: "local", подробнее здесь
  • Для CDP используйте Puppeteer через browser.getPuppeteer() или экспериментальный CDP API через browser.getCDP()

5. Если вы используете Testplane программно, добавьте await перед Testplane.create()​

В Testplane 9 вызов Testplane.create() стал асинхронным, поэтому его нужно вызывать с await:

Testplane v8Testplane v9
const Testplane = require("testplane");

export const run = async () => {
    const testplane = Testplane.create();
    /* ... */
};
const Testplane = require("testplane");

export const run = async () => {
    const testplane = await Testplane.create();
    /* ... */
};

Скорее всего, также придется обновить пакеты, которые создают инстансы Testplane, до версий, совместимых с Testplane 9.

Типовые проблемы​

к сведению

Если вас устраивают обновленные скриншоты, этот раздел можно пропустить. Здесь собраны частые вопросы о новой логике работы assertView.

На некоторых скриншотах пропали hover-эффекты​

В Testplane 9 у assertView есть опция disableHover. По умолчанию она включается, если для снятия скриншота нужен скролл, например когда целевой элемент не помещается во вьюпорт или в свой scroll-контейнер:

ExpectedActualDiff
ExpectedActualDiff

Почти всегда это полезное поведение: если сохранять hover-эффекты, в скриншоте могут появиться артефакты вроде нескольких элементов в состоянии hover или элементов с частично примененным hover-состоянием.

Если нужно вернуть старое поведение, передайте disableHover: "never":

await browser.assertView("menu", "[data-testid=menu]", {
    disableHover: "never",
});

На некоторых скриншотах пропали тултипы, поповеры, action-меню и похожие элементы​

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

ExpectedActualDiff
ExpectedActualDiff

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

Можно полностью отключить скролл во время снятия скриншота:

await browser.assertView("menu", "[data-testid=menu]", {
    captureElementFromTop: false,
    allowViewportOverflow: true,
});

Новая логика по защите от sticky/fixed элементов работает так:

  1. Вычисляется «безопасная область», свободная от sticky-, fixed- и других мешающих элементов, которые не входят в целевой элемент. Области внутри scroll-контейнера возле скруглений border-radius тоже считаются небезопасными, так как при скролле на скриншоте будут оставаться "уголки".
  2. Во время всего процесса снятия скриншота assertView старается держать целевой элемент в безопасной области. Это значит, что даже если целевой элемент целиком во вьюпорте, он может быть сдвинут в безопасную область.

assertView теперь снимает другую область​

Самая вероятная причина — область в Testplane 8 на самом деле была некорректной. Проверьте селекторы и положение элемента, наприме, с помощью Time Travel. Скорее всего, окажется, что новый скриншот окажется корректным.

В Testplane 8 были случаи, когда скриншот был просто изображением перекрывающего элемента, не относящегося к желаемым селекторам. Теперь такие случаи исправлены.

Другая возможная причина — вы используете свою кастомную команду поверх assertView, которая перед скриншотом рисует прозрачный блок поверх страницы и снимает его. Некоторые проекты прибегали к такому подходу, чтобы скриншотить псевдоэлементы или срезать скроллбары. В таком случае рекомендуем использовать обычный assertView, который в Testplane 9 умеет делать это сам.

Элементы, которые раньше рендерились поверх целевого элемента, исчезли​

Раньше на скриншот могли случайно попадать sticky/fixed-элементы, которые рендерятся поверх целевого элемента:

ExpectedActualDiff
ExpectedActualDiff

Это ожидаемое поведение: именно для этого и нужна логика обхода мешающих элементов.

Если эти элементы должны быть на скриншоте, явно добавьте их в список целевых селекторов:

- await browser.assertView("price-card", "[data-testid=price-card]");
+ await browser.assertView("price-card", ["[data-testid=price-card]", "[data-testid=close-button]"]);

Здесь на скриншот попадет минимальная область, покрывающая как цену, так и кнопку закрытия.

Другой вариант — отключить скролл, а вместе с ним и обход мешающих элементов, с помощью опций captureElementFromTop: false и allowViewportOverflow: true.

Неожиданные ошибки move target is out of bounds, падения при клике на элементы и похожие проблемы​

В Testplane 8 assertView скроллил страницу к целевому элементу, если он не был виден, снимал скриншот и оставлял страницу в измененном, проскролленном состоянии.

В Testplane 9 assertView восстанавливает исходное состояние страницы после снятия скриншота, даже если во время снятия был скролл.

Это значит, что если вы рассчитывали, что после assertView страница останется проскролленной, теперь это нужно делать явно:

await browser.assertView("price-card", "[data-testid=price-card]");

await browser.$("[data-testid=buy-button]").scrollIntoView();
await browser.$("[data-testid=buy-button]").moveTo();
/* ... */

Примечание: assertView по-прежнему скроллит страницу к целевому элементу, если он не был виден. Разница в том, что команда больше не оставляет страницу в измененном состоянии.

Поддержка​

Если во время миграции возникнут проблемы или вопросы, приходите в github issues — мы обязательно поможем!

On this page