Developer guide
Testing, docs and release
The test suite
python -m pytest -q # everything: a few minutes, no network, no Claude
python -m pytest -q tests/test_tools.py # one file
python -m pytest -q -k risk # by name
| Tests | What they cover |
|---|---|
test_platform.py, test_settingsdb.py, test_runner.py, test_cli.py, test_storage.py, test_postgres.py, test_display.py, test_auto_update.py |
The platform: settings and their history, jobs and tasks, storage, PostgreSQL, display settings, updates; every page has its help page |
test_context.py, test_tools.py, test_standards.py |
The documents: every kind's schema, a sample document through the editor, compare, approve, review, the reports; the standards; the guide pages up to date |
test_assets.py |
Asset information: registers, uploads and comparisons, the structure, failure statistics, Claude's proposals |
test_plugins.py, test_native_plugins.py, test_roadmap_plugins.py, test_publishing.py |
The plugin engine and sandbox, native plugins, each built-in plugin end to end (install, approve a document, accept the proposals, run the schedules), submission and review |
test_tenancy.py, test_isolation.py, test_signin.py, test_claude.py, test_platform_admin.py, test_hardening.py, test_restore.py, test_localfolder.py |
Hosted IMS Creator: companies kept apart, sign-in, Claude connections, the console, hardening, the restore drill, drawings from a folder |
test_phase2.py, test_convert.py, test_pipeline.py, test_eam.py, test_inventory_copy.py, test_pdf2dwg.py, test_sets_handwriting.py, test_visio.py, test_ui.py |
The drawing register, on the made-up drawings and EAM export |
test_website.py |
The marketing website |
Claude is never called: tests that need its answer give a fake client a sample document (tests/test_context.py,
sample_doc). The API is tested through FastAPI's TestClient; jobs are run with readiness.worker.run_one.
Made-up data only
No company's data is in the repository. The fixtures are made up and made by code:
tests/fixtures/make_fixtures.pydraws the drawings (tests/fixtures/drawings/1234-5678-P-000{1,2,3}.pdf, their searchable copies) and writes the EAM export (tests/fixtures/eam/assets-export.xlsx) and the EAM import templates;- the sites in the tests are fictional (Example Energy, Riverside Power Station).
The guide
docs/guide/*.md is the user guide: each page is a screen's Help in the app and a page of the wiki. Diagrams are
```mermaid blocks: the wiki draws them, and so does the in-app help. Some pages are written from the app's own
definitions, so they cannot drift from it:
python scripts/docs/guide_pages.py # write them
python scripts/docs/guide_pages.py --check # fail if one is out of date (a test runs this)
A generated part of a hand-written page sits between <!-- made from the app ... --> markers; write outside them.
The screenshots
Every screenshot, the help's and the website's (scripts/docs/website_shots.mjs, website/assets/img/app-*.webp), is
made from the code being pushed: push with scripts/push.sh, which runs scripts/docs/refresh_screenshots.sh when the
code has changed since they were made (it builds the front end and the demo site, photographs every page, draws the
website's share picture (scripts/docs/og_image.mjs), rewrites the generated help pages and the website's developer
pages, and records what code the pictures show in docs/guide/images/.made-from), commits them and pushes. The pre-push hook
(scripts/hooks/pre-push; git config core.hooksPath scripts/hooks) refuses a push whose screenshots were made from
other code, and CI's screenshots job (in publish-image.yml) goes red on one that got past it.
scripts/push.sh -u origin my-branch # refresh if need be, commit, push
scripts/docs/refresh_screenshots.sh # or only refresh them
Continuous integration and publishing
| Workflow | When | What |
|---|---|---|
publish-image.yml |
A push of code (not the docs or the website) | The test suite (with Tesseract), a dependency audit, hosted IMS Creator's tests against PostgreSQL, then the container image, scanned for vulnerabilities, and published |
publish-wiki.yml |
A change to docs/guide |
Copies the guide's pages and images to the GitHub wiki |
deploy-website.yml |
A change to website/ or scripts/website.py |
Checks and publishes the marketing website, with the developer guide under developers/ |
Before pushing: the whole suite, npx tsc --noEmit and npm run build for a front-end change (commit the build),
python scripts/docs/guide_pages.py --check, and plugins/build.sh for a change to a built-in plugin's functions; then
push with scripts/push.sh (the screenshots).
See also
- Setting up · Architecture · Server with Docker