The integration tests (ITs) live under wikantik-it-tests/. Each IT module uses Cargo to start its own Tomcat 11 against its own PostgreSQL + pgvector container (pgvector/pgvector:pg18), with every migration in bin/db/migrations/ applied and the fixtures in it-test-seed.sql loaded. Most IT failures are environmental, not code defects — a stale container, a stale WAR, a missing Docker daemon, or the wrong way of invoking Maven.
When you see red and don't yet know whether it's your code or the test harness.
The default IT modules are rest (REST + SCIM), sso (Keycloak OIDC and SAML), knowledge-disabled, custom-jdbc (the Selenide browser suite) and dense (embeddings enabled). scim-fullloop is an opt-in Authentik suite, and wikantik-selenide-tests is shared support code, not a suite of its own.
Under bin/run-tests.sh every module reserves its own free ports and its own container, named wikantik-pg-<module artifactId>, so modules do not collide with each other, with a development Tomcat on 8080, or with a development database. Collisions come back when that is bypassed: -T on a raw mvn -Pintegration-tests, or two runs in one checkout (the script takes a per-checkout lock for exactly this reason). The pgvector container is deliberately stopped rather than removed at the end of a run so its logs stay readable, which is also why a killed run leaves containers behind.
The IT phase does not rebuild anything. It runs each module with -pl <module> and no -am, against the artifacts, including the WAR, that the unit phase installed to ~/.m2. A wikantik-main unit test that fails differently on each run is a separate problem (suspect order-dependent shared state); it shows up in the unit phase, not here.
The frontmatter steps are the canonical first-aid sequence. Steps 1–4 catch the environmental issues; step 5 narrows the scope; steps 6–8 locate the actual error.
The frontmatter pitfalls are the recurring traps. Adding -T to a raw mvn -Pintegration-tests command is the most common cause of collisions — agents copy unit-test commands into IT contexts without editing. The second most common is running an IT module against a WAR built before the code change.
Cluster Hub: Agent Cookbook (agent-cookbook)