Test guidance for Codegeist contributors and coding agents.

• Read before adding or changing Java tests, smoke scripts, or verification docs.
• Read before reporting task results that include test, smoke, or startup timing.
• Read before changing app/codegeist/cli/Taskfile.yml test entrypoints or files under scripts/tests/.
• Read before adding provider feature tests, especially any method that can call a local service or remote provider API.

• Use the Taskfile from app/codegeist/cli for implementation verification.
• Prefer task test TEST=<selector> for focused checks and task test for the broader JVM suite.
• Do not document new direct mvn test commands for Codegeist implementation tasks unless a task explicitly needs Maven behavior that the Taskfile cannot express.
• Provider feature tests run through task test and method- or class-level provider categories. CODEGEIST_TEST_PROVIDER_CATEGORY defaults to none, so broad verification skips annotated provider calls. task test always starts the fixed local Ollama service first with OLLAMA_ENTER=false; set the category to local when local provider-call methods should run.
• Hosted provider calls require explicit remote_free or remote_paid category selection. API-key presence alone never enables hosted provider calls.
• task mcp-remote-smoke is the separate Docker-backed MCP streamable_http smoke. It builds and runs a local fixture container, checks the direct MCP callback path, then checks the ask plus local Ollama path. It is intentionally not part of task test.
• task devenv-smoke from app/codegeist/server is the separate Docker-backed authentik plus MinIO smoke. It proves fixture app-password client-credentials OIDC token issuance, MinIO STS temporary S3 credentials, allowed command-artifact upload/download, and denied cross-account writes without Java Codegeist Server code.
• task devenv-ai-smoke from app/codegeist/server is the separate Docker-backed Envoy AI Gateway to local Ollama smoke. It uses the separate compose.ai.yml file beside the authentik/MinIO fixture, starts or reuses the local codegeist-ollama container, protects Envoy with authentik-backed oauth2-proxy, proves unauthenticated chat-completions requests are rejected, and verifies one authenticated OpenAI-compatible request through Envoy with model llama3.2:1b and no hosted provider calls.
• task devenv-ai-up from app/codegeist/server starts the manual local Open WebUI flow. Open WebUI is available at http://172.30.198.40:8080 through the static Compose bridge IP with no host port forwarding, signs users in through authentik with the fixture user codegeist-smoke / codegeist-smoke-password, and uses Envoy AI Gateway as its internal OpenAI-compatible provider.
• There is no end-to-end Codegeist login smoke yet. Current authentik-related smokes prove partial infrastructure paths only: MinIO OIDC/STS, oauth2-proxy in front of Envoy AI Gateway, and MockMvc JWT coverage for GET /api/v1/me. A full login smoke belongs with the later server browser-login, callback, Codegeist API token issuance, CLI token storage, and /api/v1/me verification slice.
• task server:native-smoke from app/codegeist builds the Codegeist Cloud server native executable, starts it on a temporary localhost port, verifies /health, and reports native startup timing.
• Report command duration when a check is slow, platform-specific, or part of a smoke-test workflow.
• Keep smoke scripts non-interactive and make their status plus duration easy to scan in terminal output.

• provider-feature-tests.md - provider feature, category, safety, and command guidance for config-only, local, remote_free, and paid-capable provider checks.
• codegeist-test-guidelines.md - Java, Spring, provider, and task-verification test conventions.
• smoke-tests.md - Linux, Windows, release install, and MCP remote smoke-test status and duration-output contract.

• app/codegeist/cli/Taskfile.yml
• app/codegeist/cli/src/test/java/ai/codegeist/app/tui/CodegeistTerminalUiTest.java
• app/codegeist/cli/src/test/java/ai/codegeist/app/tui/TuiCommandsTest.java
• app/codegeist/cli/src/test/java/ai/codegeist/app/i18n/CodegeistLocaleServiceTest.java
• app/codegeist/cli/src/test/java/ai/codegeist/app/i18n/CodegeistMessagesTest.java
• scripts/tests/artifact-smoke.ps1
• scripts/tests/install-script-smoke.ps1
• scripts/tests/file-edit-ask-smoke.ps1
• scripts/tests/shell-ask-smoke.ps1
• scripts/tests/native-smoke.ps1
• scripts/tests/server-native-smoke.ps1
• scripts/tests/smoke-common.ps1
• scripts/tests/qemu-linux-install-smoke.sh
• scripts/tests/mcp-remote-smoke.ps1
• scripts/tests/fixtures/mcp-remote-server/
• scripts/tests/minio-oidc-storage-smoke.ps1
• scripts/tests/envoy-ai-gateway-smoke.ps1
• scripts/tests/fixtures/minio-oidc-storage/
• scripts/tests/local-linux-smoke.ps1
• scripts/tests/qemu-windows-vm.sh
• scripts/tests/qemu-windows-smoke.ps1
• scripts/tests/windows-smoke.ps1
• scripts/tests/final-smoke-suite.ps1
• docs/developer/specification/testing-strategy-and-agent-rules.md