@financial-times/pro-onboarding-tour

Professional Onboarding Tour

A user tour highlighting various FT Professional features across FT products

Installation

npm install @financial-times/pro-onboarding-tour

Basic Usage

import('@financial-times/pro-onboarding-tour').then(({ init }) => {
  init({ isDebugModeEnabled: false });
});

Development

Tech

• Node.js / npm
• Vite
• Storybook
• Web components

Directory Structure

├─ src/                       # Source code
│  ├─ index.ts                # Package public entry
│  ├─ definitions/            # global TypeScript type definitions
│  ├─ stories/                # Storybook stories (interaction examples)
│  ├─ vendor/                 # Third-party code
│  └─ lib/                    # Library code
│     ├─ init.ts              # Professional tour initialiser
│     ├─ components/          # UI web components (Overlay, TourStep, etc.)
│     ├─ services/            # Tour logic (navigation, state, loading)
│     └─ utils/               # Small pure helpers (animation, debounce)
|  |- src/test/               # Unit tests
├─ screenshots/               # Screenshots for the README
└─ .storybook/                # Storybook configuration

Setup

git clone [e-mail]:Financial-Times/pro-onboarding-tour.git
cd pro-onboarding-tour
npm install

Scripts

npm run build        # Build the library
npm run build:watch  # Watches the files and rebuilds
npm run storybook    # Run Storybook for development
npm run test         # Run tests
npm run lint         # Lint code
npm run format       # Format code

Tests

There are two type of tests - unit tests and Storybook interaction tests

Storybook interaction tests

Storybook interaction tests are written as Storybook stories that include play() functions and use storybook/test helpers and shadow-dom-testing-library to interact with the rendered component inside Storybook's iframe. A representative example is src/stories/TourContainer.stories.ts which contains end-to-end style checks implemented as steps inside play().

Under the hood these interaction tests run with Vitest via Storybook's Vitest addon (see @storybook/addon-vitest and @vitest/browser). More info:

https://storybook.js.org/docs/writing-tests/integrations/vitest-addon https://storybook.js.org/docs/writing-tests/interaction-testing

Where they live

• Story files with play() tests: src/stories/*.stories.ts
• The project config includes a separate Vitest project for Storybook tests, check vite.config.js (projects)

Running Storybook interaction tests locally

You can run the tests in two main ways:

• Dev mode (fast iteration): start Storybook in dev mode in one terminal and run the Storybook vitest project in another.

# Start Storybook dev server
npm run storybook

# Run the Storybook test project
npm run test:storybook

• Static build (same as CI): build Storybook and then run the Storybook Vitest project against the static build. This mirrors how the tests run in CI and may be more stable for UI tests.

# Build Storybook to `storybook-static`
npm run storybook:build

# Run the Storybook test project (it will pick up the static build where configured)
npm run test:storybook

How CI runs them

The CircleCI configuration builds Storybook (npm run storybook:build) and then runs the Storybook UI tests in a Playwright-enabled executor. See .circleci/config.yml jobs build-storybook and test-ui which run npm run storybook:build and npm run test:storybook respectively.

Unit tests

This repository keeps its unit tests under src/test/. Unit tests run with Vitest using the jsdom environment.

Current unit tests (under src/test/) include:

• src/test/NavigationService.test.ts
• src/test/Overlay.test.ts
• src/test/QueryParameterService.test.ts
• src/test/StepsLoader.test.ts
• src/test/TourContainer.test.ts
• src/test/TourStateManager.test.ts
• src/test/TourStep.test.ts

Running unit tests

• Run all tests (default Vitest project):

npm run test

• Run only the unit Vitest project (recommended for fast, focused runs):

npm run test:unit

• Run tests by name (match test title):

npm run test:unit -- -t "Overlay"

Local dev

• Run integrated app locally
• In the root of this package run npm link to create a global link
• In the root of your project run npm link @financial-times/pro-onboarding-tour
• Use npm run build:watch to watch the changes during development