Development environment¶

purjo utilizes devenv to provide a reproducible and feature-rich development environment. This setup includes not only the necessary Python tools but also a suite of services to simulate a production-like ecosystem.

Prerequisites¶

Install devenv
Install direnv (optional, but recommended for automatic environment activation)

Services¶

When you run devenv up, the following services are started automatically:

Operaton BPM Engine¶

Port: 8080
URL: http://localhost:8080/operaton
Description: A lightweight, open-source BPM engine. It serves as the orchestration core for your purjo tasks.
Authentication: OAuth2-protected by default (via the Keycloak service below), rather than the plain HTTP Basic credential used in older setups. Requests need either a valid OAuth2 bearer token or ENGINE_REST_AUTHORIZATION – never both (see CLI Reference).

Keycloak¶

Port: 8081
URL: http://localhost:8081
Description: An identity provider supplying OAuth2 client-credentials tokens for the Operaton engine above.
Configuration: The environment imports the operaton realm from fixture/keycloak/operaton-realm.json, including the operaton service-account client that pur authenticates as.

HashiCorp Vault¶

Port: 8200
UI: http://localhost:8200/ui
Description: A secrets management service.
Configuration: The environment automatically initializes Vault and enables the secret/ Key-Value (v2) engine. This allows you to test purjo’s Vault integration out of the box.

Mockoon¶

Port: 3080
Description: A mock API server.
Data: Configured with ./fixture/mockoon/data.json.
Usage: Useful for simulating external APIs that your Robot Framework tasks might need to interact with during development.

Dev containers¶

The project is configured to support VS Code Dev Containers. This allows you to open the project in a fully configured container environment without installing dependencies on your host machine.

Recommended extensions¶

When working with purjo in VS Code, the following extensions are recommended:

Robot Code (d-biehl.robotcode): For Robot Framework syntax highlighting and language server features.
BPMN Editor (miragon-gmbh.vs-code-bpmn-modeler): For visual editing of .bpmn files.
Ruff (charliermarsh.ruff): For Python linting and formatting.
Nix IDE (bbenoist.Nix): If you are editing devenv.nix files.

Running tests¶

$ devenv test

This command waits for all services (Operaton, Vault, Keycloak) to be ready, then runs the unit test suite (make test) followed by the end-to-end suite against those live services (make test-e2e; see End-to-end testing below). It covers the default (OAuth2) profile only; CI does not use it.

Testing strategies¶

Integration and functional testing¶

You can test your Robot Framework tasks locally without running a BPM engine using either:

Integration tests with robotframework-robotlibrary (Run Robot Test / Run Robot Task) to execute a task/test from another .robot file and assert results via variable overrides.
Functional tests with the purjo Robot Framework library (Get Output Variables) to execute a configured topic and validate the returned output variable dictionary.

See Testing Tasks for the full guide and examples.

End-to-end testing¶

purjo’s own end-to-end suite (tests/e2e/) automates exactly this flow against live services – deploy, start an instance, run pur serve, then verify the result through the engine’s history REST API.

The engine authenticates one way at a time, so the two authentication scenarios are two devenv profiles rather than two fixtures, and every e2e test is marked with the one it needs:

Profile	Engine	Marker
`shell` (the default)	OAuth2-protected, with Keycloak	`auth_oauth2`
`basic`	HTTP Basic on `/engine-rest`, no Keycloak	`auth_basic`

services.operaton asserts that its oauth2 and basicAuth options are mutually exclusive, which is why these are separate profiles. Each profile proves its own engine is actually protected rather than merely reachable: test_unauthenticated_request_is_rejected carries both markers and runs in either, and a scheme-specific test either side of it checks that the Basic credential is accepted under basic and rejected under shell.

$ devenv up                                     # OAuth2 engine (default profile)
$ cp .env.example .env                          # client credentials it needs
$ devenv shell -- make test-e2e E2E_MARKERS="e2e and auth_oauth2"

$ devenv --profile basic up                     # Basic-auth engine
$ devenv --profile basic shell -- make test-e2e E2E_MARKERS="e2e and auth_basic"

Only the OAuth2 profile needs credentials on the environment; the Basic tests pass ENGINE_REST_AUTHORIZATION to pur themselves. Never set both – see CLI Reference.

CI runs the two as separate matrix jobs, via make test-e2e-ci, which also waits for that profile’s ports and fails if a service never appears (rather than letting the suite skip itself green).

You can also drive the same flow by hand, which is what tests/e2e/ automates:

Start the services with devenv up.
Deploy your process using pur run or pur operaton deploy.
Start a process instance.
Run pur serve to execute the tasks.
Verify the results in the Operaton Cockpit or by querying the engine API.