Skip to content

Latest commit

 

History

History
365 lines (271 loc) · 13.2 KB

CONTRIBUTING.md

File metadata and controls

365 lines (271 loc) · 13.2 KB
Raw

Contributing to Testkube Dashboard

This document helps to start development of the Testkube Dashboard.

Table of Contents

  1. Set Environment
    1. Running own Testkube
      1. Custom API Version
    2. Environment Variables
    3. Starting Dashboard
  2. Code Quality
    1. Process
    2. Linter
    3. Unit Tests
    4. E2E Tests
  3. Preview
  4. Architecture
    1. Technology Stack
    2. Mono-repository
    3. Build Process
    4. Plugins System
  5. Releases
    1. Cadence
    2. Release Process
    3. Feature Flags
  6. Project Management
    1. Issue Tracking
    2. Error Reporting

Set Environment

The Dashboard is getting data from the Testkube installation.

For development, you may either:

  • use https://demo.testkube.io/results/v1 or any other existing test environment
  • run own Testkube installation

Either way, it may be useful to have Testkube CLI installed.

Running own Testkube

To run the Testkube, you need to have Kubernetes cluster, and kubectl connected to it.

✳️ Running Kubernetes cluster locally

For local development it may be easiest to use K3D, Minikube, or the one built in Docker Desktop (but it's heavy).

To install the Testkube in your cluster, you may either run testkube install command, or install it from the helm chart.

After the Testkube is installed, you should run testkube dashboard command, that will forward ports for Testkube API from your cluster to http://localhost:8088/v1.

Custom API Version

If you need to use custom API version, i.e. latest from the develop branch, you may upgrade Testkube installation to a specific version, by overriding the image tag in the Helm chart to the expected commit hash:

helm repo add kubeshop https://kubeshop.github.io/helm-charts && \
helm repo update && \
helm upgrade --install --reuse-values \
  --namespace testkube --create-namespace testkube \
  --set testkube-api.image.tag=9bd9f1b \
  kubeshop/testkube

Environment Variables

See Environment Variables section in the README file.

Starting Dashboard

Follow Running Dashboard > Repository steps to start the dashboard.

Code Quality

We aim to keep the best code quality. It doesn't mean that all the code great, yet we try to have it covered with tests, standardize the syntax, and isolate problems.

Process

To ensure that we continuously deliver good quality, most of our checks are performed automatically during the Pull Request review.

Linter

We use modified Prettier configuration (config) for code style, and lint the code against it and common mistakes with ESLint (config).

Additionally, for styles (including the styled-components) we are using StyleLint (config).

  • To run ESLint, you may run npm run lint command
  • To run Prettier, you may run npm run format:all command (but we encourage to configure IDE to run Prettier on save)
  • To run StyleLint, you may run npm run stylelint

Unit Tests

We use Jest as our main test runner. Additionally, you may use Wallaby.js to run them with better experience in the IDE.

The tests are next to tested files, with .spec.ts or .spec.tsx extension.

We aim into having unit tests for every new feature, along with the Pull Request.

  • To run unit tests, you may run npm test command
  • To run unit tests with watching for a changes, you may run npm run test:watch command
⚠️ Technical debt

Unfortunately, we have a technical debt for old components, that are not well covered. We try to write unit tests for them in spare time or when editing, but a lot is too complex to cover and needs a refactor before to reduce the complexity.

E2E Tests

We write E2E tests using Playwright. The E2E tests are in the packages/e2e-tests directory.

We aim into having unit tests for bigger features, after the release.

During the Pull Request checks, the E2E tests are run against generated Vercel preview and demo.testkube.dev's API.

  • Before running E2E tests, you need to install browser for Playwright with npx playwright install command
  • To run E2E tests, you may run npm run e2e command
  • To run E2E tests with better interface for development, you may run npm run e2e:watch
⚠️ Technical debt

We have some critical paths not covered, and we aim into covering them before new features, in spare time, or allocated time after other features.

Preview

For every Pull Request, we are deploying the frontend as a Vercel preview. When the Pull Request is created, there is automatically added a comment there, with link to the generated preview.

It's not connected to any Testkube environment, so you have to put the API endpoint there.

It has telemetry disabled - to override it, add ?~gtm_id=GTM-PQK4DKN&~disable_telemetry=false query parameters.

Architecture

Technology Stack

⚠️ Deprecation: Create React App

As CRA is deprecated for long time, we plan to move to Vite.

It has a significant effort though, especially that we are using Monaco Editor with its Webpack plugin to reduce bundle size.

⚠️ Deprecation: RTK Query

We plan to move to GraphQL (probably with Apollo) mutations, queries and subscriptions, but we need to finish ongoing back-end work before.

⚠️ Deprecation: Antd 4.x

The Antd 5.x is alive for a long time, so we may consider migrating there. It will require significant effort though.

As a side note, after migrating, we would like to have light/dark mode introduced.

⚠️ Consideration: Zustand

We may consider getting rid of Zustand, as our plugin system is able to store the data in a similar way.

It would make the code slightly simpler. The plugins system is a new thing though, so we are not fully familiar with it yet, during day-to-day development.

Mono-repository

The testkube-dashboard repository is a mono-repository configured with the NPM. All the packages are in the packages directory, and have @testkube/ name prefix.

The package that is exactly the Dashboard, is called web.

Running npm install from the root directory will install all the dependencies for all packages, while running different commands like npm run lint or npm test will do that for all packages too.

⚠️ Technical debt: Monolithic `web`

The mono-repository has been introduced lately, so we had no time yet to split the code to corresponding packages. We should improve that in the coming weeks.

⚠️ We plan to use nx in future

Thanks to that, we will be able to build boilerplate code for i.e. plugins automatically.

Build Process

When npm start is run, the development build is performed and the application with hot reload is available at localhost:3000.

To build application for the production, you have to run npm run build command.

To test application with the production build, you may run npm run start:prod command, that will build the package and serve it on localhost:3000.

Plugins System

Lately we have started efforts towards the plugins system.

Thanks to that, we are able to prepare features that are OSS-only, Pro-only or under the feature flag.

At the moment the plugins are created in packages/web/src/plugins. You may read the plugin system documentation here.

To add a new plugin, update the list in packages/web/src/AppRoot.tsx file.

⚠️ Technical debt: all the plugins are in `web` package

At the moment, because of issues with TypeScript types across packages (due to aliases in web package), all the plugins are in packages/web/src/plugins directory.

We plan to move them to separate packages in the future.

⚠️ Technical debt: some plugins are more like stubs

We have introduced the system lately, and most of the functionality is not migrated fully. Most often it's referring the components that are not lying directly in the plugin directory, but instead refer to the files from general codebase.

We plan to migrate them with time.

✳️ Future enhancement

We want to allow community plugins as well.

Releases

Cadence

We aim into having a big release once a month. We are increasing minor version (1.MINOR.0) then.

When we have some features and bugfixes ready, we release them with the patch version (1.15.PATCH).

Release process

You may use the Create Release PR manual workflow.

Alternatively, you may do steps manually:

  • Create a new release branch from develop (like release/v1.16.3)
  • Rebase on top of origin/main branch (or merge if it's not possible)
  • Create a PR to main branch
  • Merge it (don't squash!)
  • Tag the main branch to expected release (i.e. git tag v1.16.3 && git push --tags)

Feature Flags

For new features, we are able to use feature flags.

  • To check the status of the feature flag, you may use useFeatureFlag hook
  • The feature flags are added by GTM, mostly from the PostHog
  • To switch the feature flag locally, you may dispatch the feature-flags event (like const event = new Event('feature-flags'); event.data = {flag1: true}; window.dispatchEvent(event))
✳️ Future enhancement

We could allow feature flags in a similar way as we handle environment variables overrides in the query string.

Telemetry

We send custom events to GTM, that propagates them to specific places when the Trigger and Tag is created.

To track a new event, you may use useTelemetry hook:

import {useTelemetry} from '@telemetry/hooks';

const telemetry = useTelemetry();

telemetry.event('runTest', {type: details!.type});

Additionally, don't forget to update the Telemetry docs.

Project Management

Issue Tracking

We are using GitHub issues in the kubeshop/testkube repository.

Additionally, for internal project tracking we are using Linear, and Notion for specs.

Error Reporting

The errors are automatically reported in the Sentry organization, and assigned to specific releases.