Thanks for helping! The ScriptRunnerKit contributing guide and the Code of Conduct apply here. This file adds what is specific to this repository: the tools, the checks the CI runs and how releases work.
Before anything bigger than a small fix, open an issue to agree on the behavior and its acceptance criteria. Report security problems privately, as described in SECURITY.md, never in a public issue.
- .NET 10 SDK (the version in
global.json). - uv: the integration tests create real Python environments.
- Node.js 24 (
panel/.nvmrc): the dashboard UI, and Release builds that embed it. - Docker: the tests for PostgreSQL, RabbitMQ, the worker, the dashboard, the containers and the Aspire AppHost use Testcontainers or Aspire.
dotnet build
dotnet test --solution tests/PythonScriptRunner.SemE2E.slnf # unit, integration and dashboard tests
dotnet test --project tests/PythonScriptRunner.Containers.Tests # host images and compose
dotnet test --project tests/PythonScriptRunner.AppHost.Tests # Aspire AppHost
dotnet build tests/PythonScriptRunner.Panel.E2E.Tests -p:PsrBuildPanel=true
dotnet test --project tests/PythonScriptRunner.Panel.E2E.Tests --no-build # run it on its own
cd python/psrunner && uv sync && uv run pytest
cd panel && npm ci && npm testTo run everything locally with .NET Aspire, see Hosting.
| Project | Needs | Notes |
|---|---|---|
PythonScriptRunner.Core.Tests |
uv | Unit tests and integration with real Python processes. |
PythonScriptRunner.EntityFrameworkCore.Tests, .RabbitMQ.Tests, .Worker.Tests, .Dashboard.Tests |
Docker | PostgreSQL 16, RabbitMQ 3.13 and Mailpit with Testcontainers. |
PythonScriptRunner.Containers.Tests |
Docker | Builds both host images and runs them as in production (read-only, tmpfs volumes). |
PythonScriptRunner.AppHost.Tests |
Docker, Node.js and uv | Starts the Aspire AppHost and runs the sample pipelines. |
PythonScriptRunner.Panel.E2E.Tests |
Docker and the embedded UI | Drives Chromium with Playwright against a real dashboard, worker, PostgreSQL and RabbitMQ. |
Details of each project:
- Containers.Tests:
- The compose test needs the Aspire CLI (
PSR_ASPIRE_CLIpoints to it if it is not on the PATH). - To test images you built yourself, set
PSR_TEST_WORKER_IMAGEandPSR_TEST_DASHBOARD_IMAGE. - When a test fails, the logs of its containers are saved to
TestResults/container-logs/<test>/next to the test assembly, and the end of the worker and dashboard logs goes to the test output.
- The compose test needs the Aspire CLI (
- Panel.E2E.Tests:
- Build it with
-p:PsrBuildPanel=trueto embed the UI. - Run it on its own: containers starting or stopping in other test projects change the network interfaces, and Chromium
then aborts requests with
ERR_NETWORK_CHANGED. PSR_E2E_HEADED=1shows the browser.- A failed test saves its Playwright trace to
TestResults/traces(npx playwright show-trace <file>.zip).
- Build it with
- Dashboard performance test: it uses about 200,000 runs;
PSR_PERF_RUNS_PER_DAY=50000runs the full average volume (90 days). - Dashboard OpenAPI document: it is compared with
tests/PythonScriptRunner.Dashboard.Tests/Snapshots/openapi-v1.verified.json; after you review an intended change,PSR_ACCEPT_SNAPSHOTS=1updates the snapshot.
The UI lives in panel/ (Node.js 24). Debug builds of PythonScriptRunner.Dashboard embed a placeholder page; in Release
(or with -p:PsrBuildPanel=true) MSBuild runs npm ci and npm run build and embeds panel/dist.
cd panel
npm run dev # Vite at http://localhost:5173/; /api and /hubs go to the DashboardHost at PSR_DASHBOARD_URL (default http://localhost:5080)
npm test # Vitest
npm run lint # ESLint and Prettier
npm run build # type check, build and the budget of the initial bundle (500 KB gzip)
npm run api # regenerates src/api/schema.d.ts from the OpenAPI snapshotThe guides live in guides/en and guides/pt-br, with the same pages in both languages. A change in behavior updates
both, and the README when the overview changes.
A pull request is merged only when every job of .github/workflows/ci.yml is green. Run the same checks locally:
| Area | Checks |
|---|---|
| .NET | builds with warnings as errors, the latest analyzers and code style enforced in the build; dotnet format --verify-no-changes; tests on Linux, and the Core tests on Windows |
| Packages | dotnet pack produces the 7 packages with one version and their symbol packages |
| Containers | both Dockerfiles build; the images run read-only as a non-root user; the memory limit and the compose from aspire publish work |
| Python SDK | uv run ruff check src tests, uv run ruff format --check src tests, uv run mypy (strict) and uv run pytest, on Python 3.10 to 3.13 |
| Panel | npm run lint, npm run typecheck, npm run api:check, npm test and npm run build (initial bundle ≤ 500 KB gzip) |
| Dependencies | no known vulnerable NuGet packages, no high or critical npm advisories in runtime packages, pip-audit clean |
-
Tests: every acceptance criterion and every fixed bug has a test. Integration tests run against real Python (uv), PostgreSQL and RabbitMQ (Testcontainers). A test that asserts a duration gets
[Trait("Category", "Timing")]: the CI runs those alone, one at a time (--filter-trait "Category=Timing" --parallel none). -
Public API: public types and members have XML documentation (the build generates it and fails on warnings).
-
Packages: versions live in
Directory.Packages.props(Central Package Management). Dependabot proposes updates every Monday. -
Database: a change to the model needs a migration. The design-time factory opens no connection:
dotnet ef migrations add <Name> --project src/PythonScriptRunner.EntityFrameworkCore
-
Dashboard API: the OpenAPI document is a snapshot. After an intended change, accept it with
PSR_ACCEPT_SNAPSHOTS=1and regenerate the UI types withnpm run apiinpanel/. -
Contracts: the JSON Schemas in
schemas/and the protocol shared withpsrunnerare public contracts. Changing them in an incompatible way needs a new schema or protocol version. -
Changelog: user-visible changes get a line in CHANGELOG.md, under the version being prepared.
-
Commits: Conventional Commits (
feat:,fix:,docs:,test:,build:,ci:,chore:). Commit messages and pull requests describe what changed and why, so that they read on their own; link the issue when there is one.
Maintainers release from tags on main; each tag runs the full CI before anything is published.
-
.NET packages and images:
- Date the version's section in
CHANGELOG.md. - Push the tag
vX.Y.Z. release.ymlwaits for approval in thereleaseenvironment. It then publishes the 7 NuGet packages, the two multi-arch images to GHCR and the GitHub Release, with the CHANGELOG section as its notes.
MinVer takes the version from the tag. A tag with a suffix (
v0.2.0-rc.1) is published as a prerelease. - Date the version's section in
-
psrunner:
- Set the version in
python/psrunner/src/psrunner/_version.py. - Push the tag
python/vX.Y.Z. release-python.ymlpublishes it to PyPI with trusted publishing.
- Set the version in