codex-local-cli-e2e

name	codex-local-cli-e2e
description	Run and debug Agmente iOS end-to-end tests against a real local Codex CLI app-server instance. Use when validating Codex websocket/protocol compatibility, connect/initialize/thread flows, or reproducing Codex-only UI test failures with an actual local Codex server.

Codex Local CLI E2E

Overview

Run Agmente's Codex UI E2E test against a real local codex app-server, using the repo-owned scenario spec as the source of truth, collect actionable failure details, and always clean up simulator/app-server state.

Workflow

1. Resolve run inputs.

• Require endpoint (for example ws://127.0.0.1:8788) and simulator UDID.
• Decide run mode:
  • existing server: server already running.
  • managed server: start server with a provided command and stop it during cleanup.
• Read e2e/scenarios/codex/local-cli-smoke.md.
• Use references/agmente-codex-e2e-contract.md only for the UI-test environment-variable harness contract.

2. Start or verify server.

• If managed server, start the command and wait until the endpoint port is reachable.
• If existing server, verify reachability before running tests.

3. Run only the Codex UI E2E test.

• Export:
  • AGMENTE_E2E_CODEX_ENABLED=1
  • AGMENTE_E2E_CODEX_ENDPOINT=<endpoint>
• Execute targeted test only:
  • AgmenteUITests/AgmenteUITests/testCodexDirectWebSocketConnectInitializeAndSessionFlow

4. On failure, extract root cause.

• Parse xcodebuild output for the failing test and assertion.
• Read .xcresult details when xcodebuild is not explicit.
• Include failing file/line and endpoint/simulator context in the report.

5. Always clean up.

• Stop app-server if this run started it.
• Uninstall app from simulator:
  • xcrun simctl uninstall <UDID> com.example.Agmente
• Optionally shut simulator down if requested.

Preferred Execution

Use the bundled script for deterministic runs:

• scripts/run_codex_local_e2e.sh

Managed-server example:

scripts/run_codex_local_e2e.sh \
  --endpoint ws://127.0.0.1:8788 \
  --udid <SIMULATOR_UDID> \
  --start-codex-cmd "codex app-server --listen ws://127.0.0.1:8788"

Existing-server example:

scripts/run_codex_local_e2e.sh \
  --endpoint ws://127.0.0.1:8788 \
  --udid <SIMULATOR_UDID>

Reporting Requirements

Always report:

• Endpoint used.
• Simulator UDID used.
• Pass/fail status.
• Failing assertion and file/line (if failed).
• Paths to xcodebuild log and Codex server log.