Development environment¶
purjo utilizes devenv to provide a reproducible and feature-rich development environment. The unprofiled shell provides the Python and Make tooling for checks and unit tests; service-backed environments are selected explicitly with a profile.
Prerequisites¶
Install
direnv(optional, but recommended for automatic environment activation)
Services¶
Run devenv --profile oauth up to start the OAuth2 development services:
Operaton BPM Engine¶
Port:
8080URL:
http://localhost:8080/operatonDescription: A lightweight, open-source BPM engine. It serves as the orchestration core for your
purjotasks.Authentication: OAuth2-protected in this profile (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:
8081URL:
http://localhost:8081Description: An identity provider supplying OAuth2 client-credentials tokens for the Operaton engine above.
Configuration: The environment imports the
operatonrealm fromfixture/keycloak/operaton-realm.json, including theoperatonservice-account client thatpurauthenticates as.
HashiCorp Vault¶
Port:
8200UI:
http://localhost:8200/uiDescription: A secrets management service.
Configuration: The environment automatically initializes Vault and enables the
secret/Key-Value (v2) engine. This allows you to testpurjo’s Vault integration out of the box.
Mockoon¶
Port:
3080Description: 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.bpmnfiles.Ruff (
charliermarsh.ruff): For Python linting and formatting.Nix IDE (
bbenoist.Nix): If you are editingdevenv.nixfiles.
Running tests¶
$ devenv shell -- make check test
This runs static analysis and the unit test suite without starting services. To run the end-to-end suite, start the appropriate profile’s services and use the profile-specific commands below.
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.robotfile and assert results via variable overrides.Functional tests with the
purjoRobot 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 |
|---|---|---|
|
OAuth2-protected, with Keycloak |
|
|
HTTP Basic on |
|
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 oauth.
$ devenv --profile oauth up # OAuth2 engine
$ cp .env.example .env # client credentials it needs
$ devenv --profile oauth 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 --profile oauth up.Deploy your process using
pur runorpur operaton deploy.Start a process instance.
Run
pur serveto execute the tasks.Verify the results in the Operaton Cockpit or by querying the engine API.