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.py draws 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:

toolkinds.yaml, ims.yaml, analysis.KINDS

scripts/docs/guide_pages.py

plugins' plugin.yaml

a page for each document of clauses 6 to 10

the clause pages' sections

a page for each plugin

the fields of the clause 4 and 5 documents

Home's list of every document and plugin

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

scripts/docs/demo_site.py: a made-up site, documents approved, plugins installed and worked, drawings processed

serve it on :8796

scripts/docs/screenshots.mjs: every page (1440 x 900)

scripts/docs/workflow_shots.mjs: the parts of a document's page

scripts/docs/website_shots.mjs: the website's pictures

scripts/docs/images.py: PNG to WebP

docs/guide/images/.webp and website/assets/img/app-.webp

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