chatqna-api-smoke-test

<!-- SPDX-FileCopyrightText: (C) 2026 Intel Corporation SPDX-License-Identifier: Apache-2.0 --> # ChatQnA API Smoke Test Run practical API checks for ChatQnA Core using the documented endpoints in `docs/user-guide/api-reference.md`. ## Environment setup (run first) This skill operates on real ChatQnA source files, so the ChatQnA application must be present and commands must run from the app root. Do this before any API validation workflow, whether or not source is already in your workspace. Run the bundled bootstrap. It searches for an existing ChatQnA checkout by walking up from the current directory and checking the enclosing git repo, then reuses it without re-cloning. Only when no checkout is found does it do a shallow, single-branch, sparse checkout of just `sample-applications/chat-question-and-answer-core` from `main`. It prints the resolved app root on stdout: ```bash # SKILL_DIR is this skill directory. In-repo it is: # .github/skills/chatqna-api-smoke-test SKILL_DIR=".github/skills/chatqna-api-smoke-test" APP_ROOT="$(bash "$SKILL_DIR/scripts/chatqna-bootstrap.sh")" cd "$APP_ROOT" ``` Every command below assumes the working directory is this `APP_ROOT`. To use a fork/branch or a specific clone path, override these before running the bootstrap script: - `CHATQNA_REPO_URL` - `CHATQNA_REPO_BRANCH` - `CHATQNA_CLONE_DIR` - `CHATQNA_FORCE_CLONE` (set to `1` to force clone) Codebase root: `sample-applications/chat-question-and-answer-core/` ## What This Skill Produces - A runtime-aware API validation report for one scope: - Core health and metadata endpoints - Chat inference endpoint - Document ingestion lifecycle endpoints - Runtime-specific endpoints (OpenVINO device APIs or Ollama model APIs) - Raw command evidence (`curl` output + HTTP status) for each check. - A concise pass/fail summary with failing endpoint and first actionable next step. ## When to Use - "Smoke test the API" - "Validate /v1/chatqna endpoints" - "Check chat endpoint response" - "Verify Swagger/OpenAPI endpoints" - "Test runtime-specific endpoints for OpenVINO or Ollama" ## Inputs To Confirm Before running checks, confirm or infer: 1. Base host (`HOST_IP`, default `127.0.0.1`) 2. Port (default `8102`) 3. Runtime (`openvino` or `ollama`, optional but recommended) 4. Scope (`core`, `chat`, `documents`, `runtime`, or `all`; default `core`) Base URL: ```text http://<HOST_IP>:8102/v1/chatqna ``` ## Decision Logic - If scope is omitted, run `core` checks first (`/health`, `/model`, docs/openapi). - If runtime is `openvino`, include `/devices` checks. - If runtime is `ollama`, include `/ollama-models` and optional `/ollama-model` checks. - If user asks for full validation, run `all` checks. - If user asks for non-destructive tests only, avoid `POST /documents` and `DELETE /documents`. ## Smoke Test Workflow Run from `sample-applications/chat-question-and-answer-core`. ### 1. Ensure Deployment Is Running If ChatQnA is not already running, start containers before API checks: ```bash # Select runtime profile (choose one) source scripts/setup_env.sh # OpenVINO CPU (default) # source scripts/setup_env.sh -d gpu # OpenVINO GPU # source scripts/setup_env.sh -b ollama # Ollama CPU # Start services docker compose -f docker/compose.yaml up -d # Quick readiness check before API probes docker compose -f docker/compose.yaml ps ``` If deployment is already running, continue with API smoke tests. ### 2. Preflight and URL Setup ```bash HOST_IP=${HOST_IP:-127.0.0.1} BASE_URL="http://${HOST_IP}:8102/v1/chatqna" echo "${BASE_URL}" ``` ### 3. Core Availability ```bash curl -sS -w "\nHTTP_STATUS:%{http_code}\n" "${BASE_URL}/health" curl -sS -w "\nHTTP_STATUS:%{http_code}\n" "${BASE_URL}/model" curl -sS -w "\nHTTP_STATUS:%{http_code}\n" "http://${HOST_IP}:8102/v1/chatqna/docs" curl -sS -w "\nHTTP_STATUS:%{http_code}\n" "http://${HOST_IP}:8102/v1/chatqna/openapi.json" ``` ### 4. Chat API Check ```bash curl -sS -X POST "${BASE_URL}/chat" \ -H "Content-Type: application/json" \ -d '{"input":"What is Retrieval-Augmented Generation?","stream":false}' \ -w "\nHTTP_STATUS:%{http_code}\n" ``` ### 5. Runtime-Specific Checks OpenVINO: ```bash curl -sS -w "\nHTTP_STATUS:%{http_code}\n" "${BASE_URL}/devices" # Optional device detail probe curl -sS -w "\nHTTP_STATUS:%{http_code}\n" "${BASE_URL}/devices/CPU" ``` Ollama: ```bash curl -sS -w "\nHTTP_STATUS:%{http_code}\n" "${BASE_URL}/ollama-models" # Optional named model probe curl -sS -w "\nHTTP_STATUS:%{http_code}\n" "${BASE_URL}/ollama-model?model_id=<model-id>" ``` ### 6. Document API Checks (Optional) Non-destructive listing: ```bash curl -sS -w "\nHTTP_STATUS:%{http_code}\n" "${BASE_URL}/documents" ``` Upload and cleanup (run only when user explicitly requests ingestion testing): ```bash curl -sS -X POST "${BASE_URL}/documents" \ -H "Content-Type: multipart/form-data" \ -F "files=@./doc1.pdf" \ -w "\nHTTP_STATUS:%{http_code}\n" curl -sS -X DELETE "${BASE_URL}/documents?delete_all=true" \ -w "\nHTTP_STATUS:%{http_code}\n" ``` ## Failure Handling - `HTTP_STATUS` is not 2xx: - report endpoint, status code, and response body snippet - `/chat` fails: - verify request JSON includes non-empty `input` - runtime endpoint mismatch (e.g., `/devices` on Ollama): - note runtime-specific availability from API reference - docs/openapi unavailable: - verify gateway URL and service readiness via `/health` ## Completion Criteria 1. Requested scope is executed against the correct base URL. 2. Runtime-specific checks match selected runtime. 3. Response includes raw command evidence with HTTP statuses. 4. Final summary clearly marks pass/fail by endpoint. 5. For failures, provide one actionable next debugging step.