| name | sandbox-testing |
| description | Run focused tests and quality checks safely in the Codex sandbox for pflow or Loudkult. Use before testing either repository, especially when uv caches, home-directory writes, subprocess permissions, databases, Redis, or frontend tooling may behave differently inside the sandbox. |
Sandbox Testing
Detect the repository and platform
- pflow: root
pyproject.toml and root .venv/.
- Loudkult:
backend/pyproject.toml, backend/.venv/, and frontend/.
- Detect macOS, Linux, or Windows before choosing paths and shell syntax.
Operating rules
- Prefer the existing virtualenv executable over
uv run for Python, pytest, and Ruff inside the sandbox.
- Validate in layers: collection, one focused test, related files, directory, then the proportional broader suite.
- Redirect HOME only when the code under test reads or writes user state; do not change HOME reflexively.
- Treat permission, cache, service, network, and process-launch failures as environment evidence until reproduced through a focused check.
- Bound unfamiliar Windows subprocess batches to 30 seconds and stop only the exact process tree created by the run.
- Report the exact command, platform, exit status, and skipped validation. Never claim a full Make target passed when only its component tools ran.
pflow profile
Run Python tools from the repository root. Preserve pflow's encoding-warning guard so xdist workers inherit it.
macOS:
HOME=/private/tmp/pflow-test-home PYTHONWARNDEFAULTENCODING=1 \
.venv/bin/python -m pytest tests/path/test_file.py -q
.venv/bin/ruff check <paths>
.venv/bin/ruff format --check <paths>
Linux uses HOME="${TMPDIR:-/tmp}/pflow-test-home". Windows uses .venv\Scripts\python.exe; when home isolation is required, set both HOME and USERPROFILE to the same writable temp directory.
Prefer .venv/bin/pflow (or .venv\Scripts\pflow.exe) for CLI checks. Defer authoritative Windows shell, subprocess, and broad e2e behavior to pflow's Windows GitHub Actions jobs after a sandbox process failure appears.
Loudkult profile
The backend virtualenv lives under backend/; the frontend uses pnpm.
cd backend
.venv/bin/python -m pytest apps/<app>/tests/test_file.py -q
.venv/bin/ruff check <paths>
.venv/bin/ruff format --check <paths>
.venv/bin/python -m pytest ../scripts/tests -q
For frontend changes:
cd frontend
pnpm exec vitest run <path>
pnpm exec eslint <paths>
pnpm exec tsc -p tsconfig.app.json --noEmit
Backend tests may require PostgreSQL and Redis. Check make doctor; if the sandbox cannot reach or start a required service, run service-independent checks locally and leave the service-backed proof to Loudkult's Ubuntu CI. Loudkult does not use pflow's encoding-warning, redirected-home, Windows Git Bash, or pflow CLI rules unless the changed code independently introduces those concerns.
Failure signatures
- uv cache permission failure or Tokio/NULL-object startup failure: invoke the virtualenv tool directly.
- User-home write failure: redirect the relevant home variables to workspace temp storage.
- Network, credential, PostgreSQL, Redis, browser, or remote MCP failure: preserve the test and request permission or defer the exact surface to CI.
- Silent long run: poll with a bounded deadline; do not kill unrelated processes by name.
