Debugging Failing Integration Tests

The IT suite uses Cargo to start embedded Tomcat instances against a

PostgreSQL + pgvector container. Most IT failures are environmental, not

code defects — port conflicts, container leaks, or running with the

wrong Maven flags.

When to use this runbook

When you see red and don't yet know whether it's your code or the test

harness.

Context

The IT modules under `wikantik-it-tests/` each run their own Tomcat via

Cargo. They use fixed ports (8080 for HTTP, 8205 for RMI) so parallel

execution always conflicts. The pgvector container also uses a fixed

port (55432), and Docker doesn't always release it cleanly between

runs.

The wikantik-main module has a known set of parallel-flake unit tests

(per `MEMORY.md`) — they pass in isolation. They show up in unit-test

runs, not IT runs, but agents sometimes confuse the two.

Walkthrough

The frontmatter `steps` are the canonical first-aid sequence. Steps

1–3 catch the environmental issues; step 4 narrows scope; steps 5–6

locate the actual error.

Pitfalls

The frontmatter `pitfalls` are the recurring traps. The `-T 1C` flag

is by far the most common cause — agents copy unit-test commands into

IT contexts without editing.