Departurely

Important

This is a hobby project. Should not be used for commercial purpose.

The application allows to look for public transport connections between 2 stations in Switzerland. Trains and buses are taken into consideration.

Project uses transport API delivered by https://opendata.ch/

Technology stack

What can you find in this project?

• Code written in React with Next.js and Typescript

• Usage of API Routes from Next.js to make API calls

• Unit tests written with Jest

• End-to-end tests written with Playwright

• CI/CD pipeline in GitHub Actions

• Deployment to Vercel

How to start?

If you would like to start working with this project, there are several points to follow:

1. Let me know that you are willing to add or edit existing code - this way I can add you to contributors.

2. Download your favorite IDE :)

3. Install Node.js 14.6.0 or newer.

4. Clone the repository.

5. Run npm install to get all node packages.

6. Create your own .env.local file in the root of the project. Next, add 2 variables: API=http://transport.opendata.ch/v1 (to call connections API) and APPLICATION=http://localhost:3000 (to call by end-to-end tests).

7. Run npm run dev

8. Open http://localhost:3000. Note that the port might differ (especially if you run another process that uses port :3000).

9. You should see the main page that contains search form.

10. As there is no auto-suggestion for places in Switzerland, you have to type it manually. You can type whatever city in Switzerland, e.g. type Wil to from field and Geneve to to field.

Git flow

The selected way of working in this repository is Trunk-Based Development.

This means that there are no PRs and all pushes go directly to master.

The only way to work in this repository is to do pair or mob programming.

All the relevant checks are integrated into:

1. each commit (lint and tests (unit))

2. CI/CD pipeline (lint, tests (unit & e2e), build of release candidate & production)

Commits

If you would like to commit to this repository, you have to follow Conventional Commits.

There is a commit-hook which will automatically check if your commit message is correct or not. You can find in .husky folder.

The cheatsheet can be found here.

Additionally, your comit should be atomic - this means that it should touch one area at the same time. What does it mean? E.g. you want to rename a method that touches 4 files and additionally create a new method. In such situation, you will have to split your commit to 2 separate ones:

1. refactor: rename method xyz

2. feat: add new xyz method

Tests

Referring to the test pyramid, application is covered with 2 types of tests:

1. End-to-end → slower, subject to artifacts, expensive, thus the amount of it is limited to business critical paths

2. Unit tests → faster, reliable, cheaper, thus the amount of it is not limited at all

Unit tests

Tests are run & written using Jest.

To run tests locally, you can use npm run test. There you can decide if you want to watch all tests or just a part of it - follow CLI tips.

Tests files are saved in format .test.tsx for React components and .test.ts for other types.

Each test is lying next to execution code. The only exceptions are tests related to pages - they can not be there as they are treated as pages during pre-rendering.

For references on how to write them, look into existing tests.

End-to-end tests

Tests are run & written using Playwright.

To run tests locally, you can use npm run test-e2e.

Test files are saved in format .spec.ts.

Tests are lying in e2e folder. At the moment there is only 1 file related to search functionality. If there will be more features, it is suggested to split it into features folder. Furthermore, it would be nice to define steps in Gherkin to make it user-friendly.

Deployment

The selected model for the application is continuous deployment. This means that there is no manual step needed. It follows following workflow:

1. Lint, build and run unit tests.

2. Deploy release candidate (Vercel preview environment).

3. Run end-to-end tests on release candidate.

4. Deploy production environment.

If any of the above steps fails, the workflow is stopped. This way we make sure that the code deployed to production is working correctly.

At some point it would be great to put metrics & monitoring (e.g. Sentry, Prometheus, Grafana) and based on defined policies increase the traffic on release candidate before deploying the newest version into production.