Develop.md

This file provides some hints and examples how to develop PREvant.

Backend Development

You can build PREvant's backend API with cargo. For example, cargo run --bin prevant builds and starts the backend so that it will be available at http://localhost:8000.

When you than interact with the REST API to deploy service, it is worthwhile to have a look into the Traefik dashboard to double check if PREvant exposes the services as expected.

If you want to use PREvant's frontend during development, head over to the Frontend Development section.

Without any CLI options, PREvant will use the Docker API. If you want to develop with against Kubernetes, have a look into the Kubernetes section.

Kubernetes Backend

For developing against a local Kubernetes cluster you can use k3d.

1. Create a cluster:

   k3d cluster create dash -p "80:80@loadbalancer" -p "443:443@loadbalancer"

2. Start PREvant with Kubernetes (it will infer the cluster configuration by searching for kube-config file or in-cluster environment variables)

   cargo run --bin prevant -- --runtime-type Kubernetes

3. Deploy some containers and observe the result here:

   curl -X POST -d '[{"serviceName": "whoami", "image": "quay.io/truecharts/whoami:1.8.1"}]' \
      -H "Content-type: application/json" \
      http://localhost:8000/api/apps/master

4. Check Traefik's dashboard by exposing the port (see command below and detail here) and visit http://localhost:9000/dashboard.

   kubectl -n kube-system port-forward $(kubectl -n kube-system get pods --selector "app.kubernetes.io/name=traefik" --output name) 9000:9000

Frontend Development

PREvant’s frontend is located in the /frontend directory and uses npm for development and builds. You can either build the static HTML files or run the development server. There is also a section on how to run the frontend tests.

Frontend Static HTML Build

To build the static HTML files that can be served by PREvant's backend:

1. Change into the /frontend directory:

   cd frontend

2. Install dependencies:

   npm ci

3. Build the frontend:

   npm run build

Afterwards, start the backend (see Backend Development). PREvant will then be accessible at: http://localhost:8000

Frontend Development Server

To run the frontend in development mode:

1. Start the backend as described in Backend Development.

   Make also sure to pass --base-url http://localhost:9001 when starting the backend because some of the features work only if the “guessed” backend URL matches to the frontend development server URL. For example, authentication works only if the redirect URI matches relative to the dev server URL.

2. Navigate to the /frontend directory:

   cd frontend

3. Install dependencies and start the dev server:

   npm ci
   npm run serve

4. Open the following URL in your browser: http://localhost:9001

Frontend Advanced Development Scenarios

• Async API Documentation UI You can develop and test the async API UI locally at: http://localhost:9001/#/async-api-ui/%2Ffixtures%2Fasyncapi%2Fstreetlights-kafka-asyncapi.yml
• Open API Documentation UI You can also develop and test the openAPI UI locally at: http://localhost:9001/#/open-api-ui/%2Ffixtures%2Fopenapi%2Fpetstore-api-swagger.json

Frontend Tests

As part of our testing strategy, we provide support for both Unit Tests and End-to-End (E2E) Tests, ensuring that individual components work correctly in isolation and that the application behaves as expected in a real-world scenario.

Frontend Unit Tests

We use Vitest for unit testing the frontend. Unit tests ensure that individual components and utilities work as expected without relying on the full application stack.

To run all unit tests in the project:

npm run test:unit

This command outputs results in the terminal and also generates a coverage report at:

reports/frontend/coverage/index.html

Alternatively, you can run the tests in debug mode (with a UI):

npm run test:unit:ui

This will open a browser-based UI where you can:

• Filter and run individual tests.
• See real-time test results.
• Re-run tests automatically when files change.

Frontend e2e Tests

We use Playwright for end-to-end testing to simulate real user interactions and verify the entire application flow.

Before running the tests for the first time, you must install the required browsers:

npx playwright install

This only needs to be done once (or whenever Playwright updates its browser requirements).

To run the Playwright tests:

npm run test:e2e

Alternatively, you can run the tests in debug mode (with a UI):

npm run test:e2e:ui

Some tests rely on fixture files (e.g., AsyncAPI YAMLs) that are only served during development:

• We use a custom Vite plugin to serve these fixtures at /fixtures/....
• Fixture files are not included in the production build.
• This allows Playwright tests to fetch example data without relying on external URLs that may be unavailable in CI or offline environments.

Integration Testing

To test the image end-2-end, build the Docker image (docker build --pull -t aixigo/prevant .) and then choose testing via testcontainers or k3d.

Testcontainers for Docker Backend

export RUST_LOG="info,testcontainers=debug"
cargo test --package prevant-api-tests --test docker -- --test-threads=1 --nocapture

K3s for Kubernetes Backend

0. Build the bootstrap image:

   docker build --pull -t aixigo/httpd-bootstrap-example -f examples/Kubernetes/Dockerfile.bootstrap  examples/Kubernetes/

1. Create cluster and import the PREvant image:

   k3d cluster create dash -p "8080:80@loadbalancer" --no-rollback --k3s-arg --disable=metrics-server@server:* --image rancher/k3s:v1.31.7-k3s1
   k3d image import aixigo/prevant -c dash
   k3d image import aixigo/httpd-bootstrap-example -c dash

2. Deploy PREvant:

   kubectl apply -f examples/Kubernetes/RBAC-authorization.yml
   kubectl apply -f examples/Kubernetes/PREvant.yml

3. Run Tests:

   cargo test --packaeg prevant-api-tests --test k3s