Postauto Timetable Widget

Components and Widget for Postauto Timetable.

Installation

Use the node version specified in .nvmrc. Then do:

npm install

Start the project

To start the dev environment, use:

npm start

This will run the stencil dev task and the storybook task in parallel and open storybook in your browser.

!! Important !!

The start script will launch 2 npm scripts in the background. So if you want to exit the start script, you need to exit the task twice.

Start script verbosity

The start script looks rather verbose. storybook imports the components bundle from the www directory. For the first run, we need to make sure that the www directory is present, otherwise storybook will throw an error that it could not import the bundle. This is why the start script is first doing a stencil build before kicking of a parallel task of running stencil and storybook.

Linting

The linting script is automatically executed when you use git commit (via pre-commit hook). For convenience, make sure you have eslint and stylelint configured in your code editor.

To run the linting task manually, run the command:

npm run lint

To run lint for styles or eslint separately, use these commands:

npm run lint:styles

npm run lint:es

Testing

To get resilient and consistent test results locally and on CI, it is absolutely inevitable to run the tests in the same environment, no matter where they are executed. This is the reason why the tests are executed inside of a docker container.

If you execute tests locally, you first must install docker: https://docs.docker.com/engine/install/

The tests also include visual regression testing. The baseline screenshots are saved inside a snapshot folder next to each test file.

Testing locally

If you run tests for the first time, you first need to create the docker container:

npm run test:docker:build

Now you can run the tests inside the docker container:

npm run test:docker

You may also run the tests inside the docker container in UI mode. This is super helpful during development of the tests, since it makes debugging tests more easily and you can relaunch single tests as soon as you make changes to a test:

npm run test:docker:watch

Open: localhost:8080 to see the Playwright UI.

CI

On Github actions, we simply tell the workflow to use the container provided by playwright. Then we can execute tests as usual.

Visual regression

Fail on first run

If you create a new test which includes a visual regression test, the first test run will fail. This is the default behavior. Playwright wants to compare against screenshot which does not yet exist. Simply run the test again and it will pass.

Dealing with diffs

If you run into a visual diff which is intended (e.g. you increased the button font size from 16px to 17px), then you can just delete the corresponding screenshot manually and rerun the test, which will then create a new baseline image.

Next.js verification

The component is integrated into Next.js apps by Postauto. To make sure the build artifact works there, /verification/nextjs/ contains a minimal Next.js app (own package.json) with a Playwright smoke test. The verification:

1. creates a production build (npm run stencil:prod)
2. packs it with npm pack, exactly like it is published to npm, and installs the tarball into the Next.js app
3. copies the mocks and icon assets into the app's public/ folder
4. builds the Next.js app and runs the Playwright test against the /timetable route: the component must hydrate, show the search form and render results for a mocked search, without console errors or failed requests

Run it on its own with:

npm run verify:nextjs

On CI, the verification runs as part of the lint-and-test workflow after the e2e tests.

The sample route shows how to integrate the component in Next.js (see verification/nextjs/app/timetable/timetable-widget.tsx):

'use client';

import { useEffect } from 'react';
import { defineCustomElements } from '@swisspost/postauto-timetable-widget/loader';

export default function TimetableWidget() {
  useEffect(() => {
    defineCustomElements(window);
  }, []);

  return (
    <paf-timetable
      journey-service-api-url="..."
      smapi-url="..."
      smapi-contract-id="..."
      language="de"
    />
  );
}

The icons are requested from /assets/timetable-icons/, so Post needs to serve dist/assets from the package at the root of its app (e.g. by copying it to public/assets).

Extras

Event name extraction

The project contains a custom build mechanism to extract event names from the components, which stores them in a separate file for every component. See /stencil-build-helpers/rollup/event-sync.ts for info.

Generate new components

The project contains a custom boilerplate to bootstrap an new component. Use npm run generate my-new-component to create a new component with the name my-new-component.

Production build

To create a production build, run

npm run stencil:prod

The production build artifacts are saved in the the folder /dist/. Additionally, they are published on npm:

https://www.npmjs.com/package/@swisspost/postauto-timetable-widget

Release

A release will automatically be created on push or merges into master. The build artifacts will be available in the corresponding github Version under assets/dist.zip.

Backend integration

Backend integration is rather simple. In src/index-all-options.html you find an example of how to integrate the component. For documentation of all the possible attributes on the component, you can reference src/app/paf-timetable/readme.md or src/app/paf-timetable/paf-timetable.tsx.