chore: add smoke test script

Author: AlisinaDevelo

CHANGELOG.md

@@ -11,6 +11,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - Optional search filters for `lang`, `country`, `from`, `to`, and `sortBy`, with validation and normalized cache keys.
 - Prometheus metrics for article-search cache hit/miss behavior and upstream provider request latency/outcomes.
+- Curl-based `npm run smoke` check for a running instance.
 
 ## [1.2.0] — 2026-04-05
 

README.md

@@ -40,6 +40,14 @@ Development with reload:
 npm run dev
 ```
 
+Smoke-test a running instance:
+
+```bash
+BASE_URL=http://localhost:3000 QUERY=postgres npm run smoke
+# If CLIENT_API_KEYS is configured on the server:
+CLIENT_API_KEY=client-secret-one npm run smoke
+```
+
 ## Quick start (Docker)
 
 ```bash
@@ -96,6 +104,7 @@ Errors: `{ "error": "message" }`. Rate limit: `429` with standard rate-limit hea
 | `npm run test:watch` | Vitest watch. |
 | `npm run test:coverage` | Tests + coverage. |
 | `npm run lint` | ESLint. |
+| `npm run smoke` | Curl-based smoke test against a running instance (`BASE_URL`, `QUERY`, `COUNT`, optional `CLIENT_API_KEY`). |
 
 ## Project layout
 

docs/OPERATIONS.md

@@ -64,6 +64,22 @@ Or with Compose (requires `GNEWS_API_KEY` in `.env`):
 docker compose up --build
 ```
 
+## Smoke test
+
+After the service is running and ready, run:
+
+```bash
+BASE_URL=http://localhost:3000 QUERY=postgres npm run smoke
+```
+
+If `CLIENT_API_KEYS` is configured, pass a matching client key:
+
+```bash
+CLIENT_API_KEY=client-secret-one npm run smoke
+```
+
+The smoke test checks `/health`, `/ready`, `/openapi.yaml`, `/api/articles`, and `/metrics`.
+
 ## Logs
 
 Logs are **JSON** (Pino). Each response includes an `x-request-id` header for correlation.

package.json

@@ -13,7 +13,8 @@
     "test": "vitest run",
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage",
-    "lint": "eslint src test vitest.config.ts"
+    "lint": "eslint src test vitest.config.ts",
+    "smoke": "sh scripts/smoke-test.sh"
   },
   "keywords": [
     "news",

scripts/smoke-test.sh

@@ -0,0 +1,69 @@
+#!/bin/sh
+set -eu
+
+BASE_URL="${BASE_URL:-http://localhost:3000}"
+QUERY="${QUERY:-technology}"
+COUNT="${COUNT:-3}"
+
+TMP_BODY="$(mktemp)"
+trap 'rm -f "$TMP_BODY"' EXIT
+
+url_encode() {
+  node -e 'process.stdout.write(encodeURIComponent(process.argv[1]))' "$1"
+}
+
+expect_status() {
+  name="$1"
+  expected="$2"
+  url="$3"
+
+  if ! status="$(curl -sS -o "$TMP_BODY" -w "%{http_code}" "$url")"; then
+    echo "FAIL $name: request failed"
+    exit 1
+  fi
+
+  if [ "$status" != "$expected" ]; then
+    echo "FAIL $name: expected HTTP $expected, got HTTP $status"
+    head -c 500 "$TMP_BODY"
+    echo
+    exit 1
+  fi
+
+  echo "OK   $name ($status)"
+}
+
+expect_api_status() {
+  name="$1"
+  expected="$2"
+  url="$3"
+
+  if [ -n "${CLIENT_API_KEY:-}" ]; then
+    status="$(curl -sS -H "X-API-Key: $CLIENT_API_KEY" -o "$TMP_BODY" -w "%{http_code}" "$url")" || {
+      echo "FAIL $name: request failed"
+      exit 1
+    }
+  else
+    status="$(curl -sS -o "$TMP_BODY" -w "%{http_code}" "$url")" || {
+      echo "FAIL $name: request failed"
+      exit 1
+    }
+  fi
+
+  if [ "$status" != "$expected" ]; then
+    echo "FAIL $name: expected HTTP $expected, got HTTP $status"
+    head -c 500 "$TMP_BODY"
+    echo
+    exit 1
+  fi
+
+  echo "OK   $name ($status)"
+}
+
+ENCODED_QUERY="$(url_encode "$QUERY")"
+
+echo "Smoke testing $BASE_URL"
+expect_status "health" "200" "$BASE_URL/health"
+expect_status "ready" "200" "$BASE_URL/ready"
+expect_status "openapi" "200" "$BASE_URL/openapi.yaml"
+expect_api_status "articles" "200" "$BASE_URL/api/articles?query=$ENCODED_QUERY&count=$COUNT"
+expect_status "metrics" "200" "$BASE_URL/metrics"