tree: 86ae9775d387685d7ac98a8a3edcabdeace3d51a [search]
  1. .gitignore
  2. conftest.py
  3. README.md
  4. test_bell.py
  5. test_coverage_modules.py
  6. test_create_mvn_site_cli.py
  7. test_env_isolation.py
  8. test_js_tests_flags.py
  9. test_prompt_pgp_passphrase.py
  10. test_push.py
  11. test_push_timings.py
  12. test_repin_consumers.py
  13. test_run_adoption.py
  14. test_script_docs.py
  15. test_script_tests_step.py
  16. test_start_petstore_jetty.py
  17. test_test_py_console.py
  18. test_test_py_history.py
  19. test_test_py_perf.py
  20. test_test_py_profile.py
  21. test_test_py_run_command.py
  22. test_test_py_traces.py
scripts/tests/README.md

scripts/tests/

Pytest harness for the juneau-only scripts/ Python that has no other automated coverage: push.py‘s tracker-audit gate, the --js-tests flags, and repin-consumers.py. (The side-clone reset and wave-survey scripts and their tests live in the board repo’s scripts/.) Everything here is hermetic -- temp directories, synthetic fixture files, and real temporary git repositories built in fixtures -- and never touches the real ~/Project Work trackers, the real repos.md, or the real side clones.

The shared todo tracker scripts and their tests no longer live in this directory. Every file that remains here is a juneau-only script with no counterpart elsewhere.

Running

The suite must also pass under a push-like environment (JUNEAU_TERMINAL_SESSION, JUNEAU_PUSH_ACTIVE, JUNEAU_TERMINAL_ACTIVE, JUNEAU_TERMINAL_N_BASE set), because push.py‘s Python Tests step runs it that way. conftest.py strips every live-run JUNEAU_TERMINAL_* variable (LIVE_RUN_ENV: logs, cancel, header, markers, result, session and pending/overall rows) before each test, so a test never writes into the real run’s logs (test_env_isolation.py); a test that needs one sets it itself.

pytest is not vendored anywhere in this repo (it's pure-stdlib elsewhere in scripts/ on purpose). Two easy ways to run this suite without installing anything globally:

# Option A -- uv (fastest, no setup, nothing left behind):
uv run --with pytest --with pyyaml pytest scripts/tests

# Option B -- a local venv:
python3 -m venv .venv
.venv/bin/pip install pytest
.venv/bin/pytest scripts/tests

Do not pip install --user pytest / pip install pytest on a Homebrew-managed python3 -- PEP 668 (“externally managed environment”) will refuse it (or force --break-system-packages, which this repo's tooling should not depend on).

Layout

  • test_push.py -- covers the --tracker-audit opt-in gate in scripts/push.py, which only exists in juneau‘s copy (release-manager’s push.py is a bare add/commit/push helper with no gates at all; sandbox-support-console has no push.py). Its central assertion is that the off path never reaches subprocess.run at all -- not just that it returns early -- which is the strongest available proof the gate cannot affect push behavior, including runtime, while disabled. It also covers the workflow-YAML guard (TestWorkflowYamlGuard), which needs PyYAML: run it with uv run --with pytest --with pyyaml pytest scripts/tests/test_push.py.

  • test_js_tests_flags.py -- the --js-tests / --no-js-tests support in scripts/test.py and scripts/push.py: flag parsing (incl. conflict rejection and push.py forwarding the flags to test.py), auto-detect of changed .js/.css/.ftl files under src/ (driven by a fake changed-file list, no git), and the Node/npm-missing path (skip with notice when auto-enabled, fail when explicit). Never runs mvn or push.py's real flow.

  • test_test_py_run_command.py -- scripts/test.py's run_command() streams each output line to the console as it arrives (stderr merged in) instead of buffering until the command exits, and still returns the full output and exit code. The second test proves a line is echoed while the command is still running. Uses trivial shell commands, never mvn.

  • test_run_adoption.py -- push.py and test.py on juneau-terminal: marker streams from a fake mvn on PATH, push.py --test-only, console routing, the skipped second install, the commit summary, the Timing row, the nested test.py handoff and --detail. It also pins the default (markers off) behaviour.

  • test_test_py_console.py -- test.py's console session: --detail, the PERF-GUARD notes and their levels under --enforce-perf, and -f on the JS-test command.

  • test_push_timings.py -- push-timings.py's thresholds: a module is flagged only when it is slower by both the relative and the absolute margin, faster modules get the ↓ mark, the env overrides, and the --report table file. Synthetic run-history records in a temp dir.

Shared fixtures in conftest.py: run_history (F1) turns run history on for one test under tmp_path/history, with argv[0] set so the writer's script name is test; fake_reports (F2) builds a scratch Surefire tree; and history_record (F3) builds one run-history record.

  • test_repin_consumers.py -- repin-consumers.py re-pins the other two repos (Release Manager, Support Console) to a fresh local Juneau build, so it lives and is tested only here. Covers the script's whole reason to exist -- the dirty-tree guard that refuses to mvn install Juneau into the shared ~/.m2 unless git status --porcelain is empty (modified tracked files, staged-only changes, and untracked non-ignored files are each proven to trip it; a gitignored untracked file is proven not to) -- plus the small pure helpers around it (pom <version> parsing, HEAD-vs-origin/master comparison) and main()‘s exit-code contract. The refusal path is proven by monkeypatching run_streaming to raise if it is ever called, so “refused” means “mvn was never invoked”, not just “the exit code was 1” -- the same style test_push.py uses. Built against real temporary git repositories for the same reason that one is: the guard’s entire risk is real git status --porcelain behavior, which a mocked subprocess would let pass while proving nothing. Never runs a real mvn command.

  • test_script_docs.py -- the script-docs checker. Every runnable script under scripts/ (a .py file with a __main__ guard, a .sh file, or an extensionless file with a shell or Python shebang) needs a <name>.md beside it with the seven standard sections (When to use, Usage, Options, What it does, Output and exit codes, Gotchas, See also), and every flag the script declares must appear in backticks in the doc's Options section. It reads source with ast and text matching and never runs a script. Flags come from literal add_argument and add_parser calls, or from the option case block of a shell script; an argparse script with no literal calls fails as FLAGS-UNVERIFIABLE unless excluded. A doc listing a flag the script does not declare only warns. Exceptions go in scripts/script-docs-exclude.txt, one per line as pattern # reason (reason required), with a flags: prefix to skip only the flag check and a packages: prefix for library directories that need a README.md instead; a pattern that matches nothing fails. Tests, vendor, node_modules, __pycache__ and fixtures directories are never scanned. The checker also unit-tests its own parsers and proves each check fails when broken.