C4 Connectors

Storybook

When opening a PR, a version of storybook with the changes is deployed automatically and can be accessed by clicking on the link in the PR.

Dev

🔧 Preparation

There are a few npm packages only available to Camundis, so you first need to create a personal access token on GitHub. To create this token, follow the steps below:

1. Go to https://github.com/settings/tokens.
2. Click Generate new token.
3. Select at least read:packages.
4. Generate the token.
5. Keep the generated token in a safe place (e.g. the Camunda secrets management) because you will never see it again. Important: Enable SSO to allow the token to access the camunda-cloud artifacts.
6. Add the generated token to your environment. See the example below for Linux: export NPM_TOKEN=ghp_imiJmvG46E6wo7V4ANwurstbrotXafCg
7. Next, run the following: npm i

NOTE: It is highly suggested you add the export-statement to your .profile so it is added to your environment automatically.

💻 Installation

# install
yarn

# start storybook
yarn storybook

# build components
yarn build

▶️ Running with Console SM

See this documentation for more information. TLDR; Use the following environment variables to get a minimal setup running:

#build the project, go to the root directory (camunda-cloud-management-apps)
pnpm build

# camunda-cloud-management-apps/apps/console-sm-backend
NODE_ENV=local SERVICE_NAME=console-sm-backend CAMUNDA_CONSOLE_DISABLE_AUTH=true pnpm run start

# camunda-cloud-management-apps/apps/console-sm-frontend
pnpm run start:local

Navigate to localhost:4200 to open Console. Since the configmap content is just dummy information, fetching of all external data will fail (metrics for telemetry from webapps, ...).

💡 The environment variable CAMUNDA_CONSOLE_DISABLE_AUTH disables login for Console. That setup simplifies a local instance because there's no dependency that needs to be set up.

💡 The configmap content for the local instance is available in application.yaml.

🎁 Release

Official release

Simply run our release workflow in the GitHub Actions tab. This will create a new release, publish the package to npm and update the changelog automatically.

Local release

You can use YALC to deploy the package locally. Then you can use the package in another project by adding workspace: to the dependency version in the package.json.

🧪 Testing

Visual regression tests (VRT)

We use Playwright screenshot tests to be aware of any visual changes introduced by dependency updates or changes in the component code.

Running VRT locally

We run VRT inside a docker container to avoid different results caused by different platforms. Simply run:

yarn start:docker-storybook

then

yarn test:visual-regression:docker

The commands above will:

1. Build storybook.
2. Start a Playwright docker container with the name c4-visual-regression.
3. Serve storybook within the docker container.
4. Run the visual regression tests within the docker container.

When developing, it might not always be helpful to run all of these steps at once. You can find more granular scripts in the package.json.

Running VRT in the CI

There is a Visual regression tests workflow that is triggered automatically on push. You can also trigger it manually in the Actions tab.

If the workflow fails, you can find the test report by navigating to the workflow run summary, then scrolling down to the Artifacts section. Click on the artifact called Playwright report to download it, go to your downloads folder, then open the index.html file of the test report in your browser to view the report.

How to deal with failing tests

When a VRT fails, this can have two reasons:

1. A change was introduced unknowingly. In this case, have a look at the test report and check if the change was intended. If it is, proceed with 2.
2. You made a change to the UI on purpose. In this case you need to update the screenshot as follows.

Make sure you have the c4-visual-regression docker container running, or start it like described here. Then, have a look at the test report:

yarn report:visual-regression

Double-check that you don't apply any unwanted changes by looking at the difference that is highlighted in the failed test's report.

To update all screenshots, run:

yarn update:visual-regression:docker

The tests should now pass locally and in the CI. Commit and push the updated screenshot(s).