Интеграционное тестирование

Shepherd.js — это библиотека для создания интерактивных пользовательских инструкций и пошаговых туров в веб-приложениях. Основная задача — управлять последовательностью подсказок, их позиционированием и поведением при взаимодействии с пользователем. Shepherd.js построен поверх Popper.js, что позволяет точно позиционировать подсказки относительно элементов DOM.

Ключевые объекты:

  • Tour — основной объект, управляющий всеми шагами тура.
  • Step — отдельный шаг тура с собственным содержимым и поведением.
  • Button — элементы управления внутри шага, например, кнопки «Далее», «Назад» и «Закрыть».

Инициализация тура

Создание нового тура начинается с инициализации объекта Shepherd.Tour:

const tour = new Shepherd.Tour({
  defaultStepOptions: {
    cancelIcon: {
      enabled: true
    },
    scrollTo: { beh * avior: 'smooth', block: 'center' },
    classes: 'shepherd-theme-arrows'
  },
  useModalOverlay: true
});

Пояснения:

  • defaultStepOptions задаёт общие параметры для всех шагов, например, стили или скроллинг к элементу.
  • useModalOverlay включает затемнение фона для фокусировки на текущем шаге.

Создание шагов

Каждый шаг создаётся методом addStep:

tour.addStep({
  id: 'intro',
  text: 'Добро пожаловать в наш интерфейс!',
  attachTo: {
    element: '#start-button',
    on: 'bottom'
  },
  buttons: [
    {
      text: 'Далее',
      action: tour.next
    },
    {
      text: 'Закрыть',
      action: tour.cancel
    }
  ]
});

Ключевые моменты:

  • id — уникальный идентификатор шага, полезен для управления и тестирования.
  • text — содержимое подсказки, поддерживаются HTML и стили.
  • attachTo — объект с указанием элемента и позиции (top, bottom, left, right) относительно него.
  • buttons — массив объектов кнопок с привязкой к методам тура (next, back, cancel).

Управление туром

Основные методы:

  • tour.start() — запуск тура с первого шага.
  • tour.next() — переход к следующему шагу.
  • tour.back() — возврат к предыдущему шагу.
  • tour.cancel() — завершение тура.
  • tour.complete() — отметка тура как завершённого без отмены.

Shepherd.js автоматически отслеживает видимость и позицию элементов, но при динамических интерфейсах можно использовать события DOM для обновления шага:

window.addEventListener('resize', () => {
  tour.currentStep.updateStepElement();
});

Настройка внешнего вида

Shepherd.js поддерживает темы и кастомные CSS-классы. Например:

const tour = new Shepherd.Tour({
  defaultStepOptions: {
    classes: 'shepherd-theme-arrows custom-tour',
    arrow: true
  }
});
  • classes — добавляет собственные классы для кастомизации.
  • arrow — отображение стрелки, указывающей на элемент.

Для глобальной настройки стилей можно использовать CSS:

.shepherd-theme-arrows.custom-tour .shepherd-header {
  background-color: #1e90ff;
  color: #fff;
}
.shepherd-theme-arrows.custom-tour .shepherd-button {
  background-color: #f0f0f0;
  border-radius: 4px;
}

Интеграционное тестирование Shepherd.js

При интеграционном тестировании важно проверить:

  1. Корректное появление шагов. Каждый шаг должен отображаться на правильной позиции относительно элемента.
  2. Последовательность шагов. Переход по шагам должен соответствовать логике приложения (next, back).
  3. Реакция на динамический DOM. Элементы могут появляться или исчезать, тест должен учитывать attachTo и обновление шага.
  4. Обработка кнопок управления. next, back, cancel и кастомные действия должны корректно работать.
  5. Визуальные эффекты. Проверка тем, стрелок и модального оверлея.

Для тестирования можно использовать фреймворки типа Cypress или Playwright:

describe('Shepherd Tour Integration', () => {
  it('Проверка первого шага тура', () => {
    cy.visit('/app');
    cy.window().then(win => {
      win.tour.start();
    });
    cy.get('.shepherd-step').should('contain.text', 'Добро пожаловать');
    cy.get('.shepherd-button').contains('Далее').click();
    cy.get('.shepherd-step').should('contain.text', 'Следующий шаг');
  });
});

Рекомендации по тестированию:

  • Проверять поведение тура на разных разрешениях экрана.
  • Модальные оверлеи должны блокировать взаимодействие с остальными элементами.
  • Использовать уникальные id шагов для удобной навигации в тестах.

События и обратные вызовы

Shepherd.js предоставляет события для расширенного контроля:

tour.on('start', () => console.log('Тур начался'));
tour.on('complete', () => console.log('Тур завершён'));
tour.on('show', step => console.log(`Показан шаг: ${step.id}`));
tour.on('cancel', () => console.log('Тур отменён'));
  • start — запуск тура.
  • show — показ конкретного шага.
  • complete и cancel — завершение или отмена тура.
  • Можно подписываться на события для интеграционных тестов и логирования поведения.

Динамические шаги и условия

Шаги можно добавлять динамически в зависимости от состояния приложения:

if (user.isAdmin) {
  tour.addStep({
    id: 'admin-step',
    text: 'Административные функции доступны здесь.',
    attachTo: { element: '#admin-panel', on: 'right' },
    buttons: [{ text: 'Далее', action: tour.next }]
  });
}

Такой подход позволяет адаптировать тур под разные роли пользователей и проверять логику во время интеграционных тестов.

Оглавление