To start the development environment, you need Node.js (v12 LTS recommended) and Yarn as package manager.

The usage of Nix to install system-level packages is recommended.

Ensure that Node.js and Yarn are available in your environment

Either use the installers

• Node.js installer
• Yarn installation

Or – if using Nix – entering a new Nix shell will install Node.js and Yarn automatically:

nix-shell

Run the setup script:

yarn setup

This will install npm dependencies and run setup scripts.

Once the application's set up, you can start the development server with

yarn dev

👉 In Visual Studio Code, you also can run the default build task (CMD-SHIFT-B) to start the dev server, database server, and TypeScript checker (you'll need Nix for that to work).

New versions of package.json are built on CI into a separate image that will be deployed to the test environment.

yarn version

This will prompt for a new version. The postversion script will automatically try to push the created version tag to the origin repo.

Docker TBD

New localizable strings can be extracted from the source code with

yarn locales:extract

This will update the translation files in src/locales/*/messages.po.

After updating the translation PO files, run

yarn locales:compile

To make the translations available to the application. Note: this step will run automatically on yarn build.

Run

make geodata

Since Switzerland's municipalities can change each year, the yearly Shapefiles from 2010 on prepared by BFS will be downloaded and transformed into TopoJSON format which can be loaded efficiently client-side.

The detailed transformation steps are described in this project's Makefile.

On CloudFoundry, an HTTP proxy is used for external requests. This is for example used to fetch the gitlab content. The proxy is configured via the ./configure-proxy.js script that is required in the package.json start command. It uses the HTTP_PROXY environment variable

• For some of the server requests (SAML requests), we must not use this proxy, and the agent is configured there manually.
• For external requests that should use the proxy, we can use https.globalAgent.

const https = require('https')
const data = fetch(url, {
  agent: https.globalAgent
})

EIAM certificates are used to authenticate against the GEVER API serving the electricity provider documents.

They are stored in 1Password as "Elcom PWD certificates".

EIAM certificate content and password are passed as environment variable. The certificate content is a p12 certificate encoded as base 64.

In dev, you have to edit env.local to add the EIAM_CERTIFICATE_CONTENT and EIAM_CERTIFICATE_PASSWORD variables.

# Get the base64 certificate content that can be put in EIAM_CERTIFICATE_CONTENT
cat ../../../vault/svc.spw-d.elcom.admin.ch.p12 | base64

To load test, we use the k6 platform and its ability to import HAR session recordings. We generate automatically a HAR via a Playwright test designed to mimick a typical user journey and import it into k6.

After an update to the application, it is necessary to update the test on k6 so that the chunks URL are correct. To make the update painless, Playwright is used to automatically navigate across the site, and then save the session requests as an HAR file.

1. Record the HAR

The HAR is generated automatically from a Playwright test.

yarn run e2e:k6:har

You can also generate an HAR from a different environment than ref by using the ELCOM_ENV env variable.

ELCOM_ENV=abn yarn run e2e:k6:har

The command will open a browser and will navigate through various pages. After the test, an HAR will be generated in the root directory.

2. Import the HAR file into K6

yarn e2e:k6:update

ℹ️ Check the command in package.json if you want to change the HAR uploaded or the test being updated

Make sure the options of the Scenario correspond to what you want as k6 resets them when you import the HAR (you might want to increase the number of VUs to 50 for example).

The preferred way to edit the test is to use the Recorder inside VSCode. This way it is easy to quickly generate a test.

• Add testIds in case the generated selectors are not understandable.
• Add sleeps to make sure the test is not too quick and "human like"