# CLI Unit Test Port Plan

## Objective

Replace the Python-based network test runner and plugins with UCE unit tests invoked through the runtime's CLI socket path, keeping equivalent coverage for HTTP smoke, site suites, security checks, starter parity, TCP/WebSocket listener probes, and wasm kill checks. The final invocation should be a bash script that calls UCE CLI units; Python test files should be removed only after UCE coverage is in place and validated.

## Success Criteria

- [x] A bash command runs the full test suite through the CLI socket and exits nonzero on failure.
- [x] UCE CLI tests cover every current Python plugin behavior or explicitly document a deliberate replacement.
- [x] Existing W5/WASM gates use the UCE CLI test runner instead of `tests/run_network_tests.py`.
- [x] Python test runner/plugins are deleted after parity validation.
- [x] Full suite passes on `uce-dev` with wasm-only unit execution.

## Current State

- Status: verifying
- Last updated: 2026-06-13
- Source of truth: `/root/mount_ssh/uce-dev-root-htdocs-uce`
- Runtime/live target: `uce-dev:/Code/uce.openfu.com/uce`

## Goal Tree

Legend: `[ ]` not started, `[~]` in progress, `[x]` done, `[!]` blocked, `[-]` superseded

- [x] G1: Inventory Python test coverage and CLI constraints
  - Why: replacement must preserve coverage before deleting Python.
  - Done when: every plugin has a mapped UCE equivalent or blocker.
  - Verify: coverage matrix in this document.
  - [x] G1.1: Delegate design/coverage review to Spark.
  - [x] G1.2: Inspect delegates and reconcile plan.
- [x] G2: Build UCE CLI test harness
  - Why: Python runner features need a UCE-native replacement.
  - Done when: one CLI unit can list/run tests, print pass/fail summary, and return failing CLI status.
  - Verify: `scripts/run_cli_tests.sh --list` and `scripts/run_cli_tests.sh --include-wasm-kill`.
  - [x] G2.1: Add reusable UCE assertion/reporting helpers.
  - [x] G2.2: Add HTTP/TCP helper functions using UCE socket APIs.
  - [x] G2.3: Add bash wrapper under `scripts/`.
- [x] G3: Port current plugin cases to UCE
  - Why: only delete Python after equivalent UCE coverage exists.
  - Done when: UCE suite covers demo, HTTP docs/starter, site suites, security, starter parity, TCP, wasm kill.
  - Verify: UCE CLI full run passes and output names match coverage matrix.
- [x] G4: Replace Python gate usage and delete Python tests
  - Why: user explicitly requested eliminating the Python suite.
  - Done when: scripts no longer call `tests/run_network_tests.py`, Python test files removed, validation green.
  - Verify: `rg 'run_network_tests|tests/plugins|python3 tests'` has no obsolete gate references except historical docs and benchmark/audit utilities.
- [~] G5: Document and validate
  - Why: future agents/operators need the new test workflow.
  - Done when: docs/project notes and in-repo docs mention the CLI test command and validation artifact.
  - Verify: docs committed, full suite run artifact recorded.

## Coverage Matrix

- `uce_demo_smoke.py` → `cli_run_demo_smoke()` in `site/tests/cli_runner.uce` (43 demo pages).
- `uce_http_smoke.py` → `cli_run_http_smoke()` (docs and starter route/body checks, 14 cases).
- `uce_site_suite.py` → `cli_run_site_suite()` (manifest-driven published site suite pages, 13 cases).
- `uce_security_smoke.py` → `cli_run_security_smoke()` (direct HTTP traversal/header spoofing, CRLF header sanitization, session hardening, 4 cases).
- `uce_starter_parity.py` → `cli_run_starter_parity()` (starter view title/404 checks, 7 cases).
- `uce_tcp_smoke.py` → `cli_run_tcp_smoke()` (port 80 and 8080 reachability, 2 cases).
- `uce_wasm_kill.py` → `cli_run_wasm_kill()` gated by `--include-wasm-kill` (trap/loop/recurse + post-kill health checks, 3 cases).

## Execution Queue

1. Run final no-Python-suite validation after removing stale references.
2. Commit UCE and project-doc updates.

## Decisions

- 2026-06-13: Use UCE CLI socket invocation as the test entrypoint; bash wrappers are acceptable, Python runner/plugins are not.
- 2026-06-13: Do not delete Python tests until UCE replacement validates equivalent coverage on `uce-dev`.

## Assumptions

- UCE socket APIs are sufficient for HTTP/1.0 probes, TCP connect checks, and security header injection checks.
- Bash can provide filtering/list convenience if exact Python CLI parity is not needed.

## Blockers and Risks

- [ ] The new runner intentionally does not preserve the old Python runner's dynamic plugin/tag/regex filtering; add UCE-side selectors later if operators miss them.
- [ ] `tests/wasm_benchmark.py` and `tests/wasm_site_audit.py` remain Python utility scripts, not the network test suite; port separately if a strict no-Python tools policy is desired.

## Evidence and Verification Log

- 2026-06-13: Prior to this plan, `b1856c1 chore: narrow wasm backend entrypoint API` was committed after build and focused services validation.
- 2026-06-13: `scripts/run_cli_tests.sh --include-wasm-kill` on `uce-dev` passed `86 passed, 0 failed, 0 skipped` (`/tmp/uce/cli-tests-final.txt`).

## Change Log

- 2026-06-13: Created initial goal tree for CLI unit test port.
- 2026-06-13: Added `site/tests/cli_runner.uce`, `scripts/run_cli_tests.sh`, removed Python network runner/plugins, and repointed W5 network gates to the CLI runner.