Cursor rule

1---
2description: "Post-deploy health-check against a live URL. Validates HTTP status, response content, and critical endpoints. Runnable standalone OR as the final step of the deploy skill."
3alwaysApply: false
4---
5 
6# Smoke Test
7 
8> **HARD GATE** — Do NOT run smoke-test against a URL that hasn't been deployed yet. Always run `deploy` first, then `smoke-test`.
9>
10> **HARD GATE** — A failed smoke test means the deployment is broken. Do NOT mark a deploy as successful until all smoke checks pass.
11 
12Validate a deployed application is healthy by running HTTP checks against live URLs. Each check asserts HTTP status, optional body signal (regex), and optional response-time threshold.
13 
14## Configuration
15 
16Smoke checks live in `smoke-checks.yaml` at the project root:
17 
18```yaml
19base_url: "https://example.com"
20checks:
21  - name: "Homepage"
22    path: "/"
23    expected_status: 200
24    content_signal: "welcome|ok"
25    max_response_time_ms: 3000
26```
27 
28| Field | Required | Default | Description |
29|-------|----------|---------|-------------|
30| `name` | Yes | — | Human-readable check name |
31| `path` | Yes | `/` | URL path relative to base_url |
32| `method` | No | `GET` | HTTP method |
33| `expected_status` | No | `200` | Expected HTTP status code |
34| `content_signal` | No | — | Regex or string in response body |
35| `max_response_time_ms` | No | — | Fail if slower than threshold (ms) |
36 
37Ad-hoc single-URL mode: `DEPLOY_URL=https://host bash scripts/run-smoke.sh`
38 
39## Process
40 
41### 1. Load checks
42 
43```bash
44SMOKE_CHECKS_FILE="${SMOKE_CHECKS_FILE:-smoke-checks.yaml}"
45BASE_URL="${DEPLOY_URL:-$BASE_URL}"
46test -f "$SMOKE_CHECKS_FILE" || test -n "$BASE_URL" || { echo "ERROR: no checks file or URL"; exit 1; }
47```
48 
49### 2. Run each check
50 
51```bash
52bash scripts/run-smoke.sh "${DEPLOY_URL:-}" "${SMOKE_CHECKS_FILE:-smoke-checks.yaml}"
53```
54 
55The runner performs curl requests per check, records pass/fail per assertion, and prints a summary.
56 
57### 3. Assert results
58 
59- Any HTTP status mismatch → FAIL
60- Missing `content_signal` when configured → FAIL
61- Response time over `max_response_time_ms` → FAIL
62- Exit code non-zero → deployment not healthy
63 
64### 4. Generate report
65 
66Capture stdout from `run-smoke.sh` as evidence. Persist to `specs/verifications/smoke-<date>.log` for release-branch.
67 
68## Integration with deploy skill
69 
70```bash
71DEPLOY_URL=&quot;$DEPLOY_URL&quot; bash scripts/run-smoke.sh
72```
73 
74## Verify arc
75 
76Part of **★ VERIFY ★**: `verify-work` → `validate-contracts` → `smoke-test` → `run-evals` → `audit-code`
77 
78## Verify
79 
80→ verify: `test -x scripts/run-smoke.sh && grep -q 'run-smoke.sh' skills/smoke-test/SKILL.md && ! grep -q 'See \[REFERENCE.md\](REFERENCE.md)$' skills/smoke-test/SKILL.md && echo OK`
81 
82---
83 
84# Smoke Test — Reference
85 
86## Navigation
87 
88| Lines | Section |
89|-------|---------|
90| 1 | Title |
91| 3–17 | Navigation |
92| 18–34 | Runner script |
93| 35–46 | Configuration reference |
94| 47–55 | Verification |
95| 56–89 | Reference block 1 |
96| 90–107 | Reference block 2 |
97| 108–122 | Reference block 3 |
98| 123–159 | Reference block 4 |
99| 160–177 | Reference block 5 |
100 
101## Runner script
102 
103A ready-to-use runner is provided for standalone operation:
104 
105```bash
106bash scripts/run-smoke.sh [url] [smoke-checks-file]
107```
108 
109The runner:
1101. Uses `$DEPLOY_URL`, `$SMOKE_CHECKS_FILE`, or CLI arguments
1112. Runs all defined checks
1123. Prints a pass/fail summary
1134. Exits 0 on all pass, non-zero on any failure
114 
115 
116---
117 
118## Configuration reference
119 
120| Variable | Default | Description |
121|----------|---------|-------------|
122| `SMOKE_CHECKS_FILE` | `smoke-checks.yaml` | Path to smoke checks YAML |
123| `DEPLOY_URL` / `BASE_URL` | *(required)* | Base URL for all checks |
124| `SMOKE_TIMEOUT` | `30` | Per-check timeout (seconds) |
125| `SMOKE_RETRIES` | `0` | Number of retries on failure |
126 
127 
128---
129 
130## Verification
131 
132→ verify: `test -f smoke-test/SKILL.md && grep -q 'name: smoke-test' smoke-test/SKILL.md && echo OK`
133→ verify: `grep -qi 'smoke.checks.yaml\|checklist\|expected_status\|content_signal' smoke-test/SKILL.md && echo OK`
134→ verify: `grep -ci 'pass\|fail\|summary\|report' smoke-test/SKILL.md | awk '{if($1>=2) print "OK"; else print "FAIL"}'`
135→ verify: `grep -q 'smoke-test' SKILL-INDEX.md && echo OK`
136 
137---
138 
139## Reference block 1
140 
141```yaml
142# smoke-checks.yaml — auto-loaded if present at project root
143base_url: "https://example.com"
144checks:
145  - name: "Homepage"
146    path: "/"
147    method: GET
148    expected_status: 200
149    content_signal: "bigpowers"
150    max_response_time_ms: 3000
151
152  - name: "API Health"
153    path: "/api/health"
154    method: GET
155    expected_status: 200
156    content_signal: "ok|healthy"
157
158  - name: "API Jogos"
159    path: "/api/jogos"
160    method: GET
161    expected_status: 200
162    content_signal: "jogos|games"
163
164  - name: "Not Found handling"
165    path: "/nonexistent"
166    method: GET
167    expected_status: 404
168    content_signal: "not found|404"
169```
170 
171---
172 
173## Reference block 2
174 
175```bash
176SMOKE_CHECKS_FILE=&quot;${SMOKE_CHECKS_FILE:-smoke-checks.yaml}&quot;
177BASE_URL=&quot;${DEPLOY_URL:-$BASE_URL}&quot;
178
179if [ -f &quot;$SMOKE_CHECKS_FILE&quot; ]; then
180  echo &quot;Loaded smoke checks from $SMOKE_CHECKS_FILE&quot;
181elif [ -n &quot;$BASE_URL&quot; ]; then
182  echo &quot;No smoke-checks.yaml found. Using single URL check against $BASE_URL&quot;
183else
184  echo &quot;ERROR: No smoke-checks.yaml found and no DEPLOY_URL/BASE_URL set.&quot;
185  exit 1
186fi
187```
188 
189---
190 
191## Reference block 3
192 
193```bash
194url=&quot;${BASE_URL}${path}&quot;
195start_time=$(python3 -c 'import time; print(int(time.time() * 1000))')
196 
197# Perform the HTTP request
198response=$(curl -s -o /tmp/smoke_body.txt -w &quot;%{http_code}&quot; &quot;$url&quot;)
199response_time=$(( $(python3 -c 'import time; print(int(time.time() * 1000))') - start_time ))
200status=$response
201body=$(cat /tmp/smoke_body.txt)
202```
203 
204---
205 
206## Reference block 4
207 
208```bash
209checks_passed=0
210checks_failed=0
211failures=&quot;&quot;
212 
213# Assert status code
214if [ &quot;$status&quot; -ne &quot;${expected_status:-200}&quot; ]; then
215  echo &quot;  FAIL: expected status ${expected_status} but got $status&quot;
216  checks_failed=$((checks_failed + 1))
217  failures=&quot;${failures}  - $name: HTTP $status (expected ${expected_status})\n&quot;
218else
219  echo &quot;  PASS: HTTP $status&quot;
220fi
221 
222# Assert content signal
223if [ -n &quot;$content_signal&quot; ]; then
224  if echo &quot;$body&quot; | grep -qiE &quot;$content_signal&quot;; then
225    echo &quot;  PASS: body contains \&quot;$content_signal\&quot;&quot;
226  else
227    echo &quot;  FAIL: body does not contain \&quot;$content_signal\&quot;&quot;
228    checks_failed=$((checks_failed + 1))
229    failures=&quot;${failures}  - $name: missing content signal \&quot;$content_signal\&quot;\n&quot;
230  fi
231fi
232 
233# Assert response time
234if [ -n &quot;$max_response_time_ms&quot; ] && [ &quot;$response_time&quot; -gt &quot;$max_response_time_ms&quot; ]; then
235  echo &quot;  FAIL: response time ${response_time}ms exceeds ${max_response_time_ms}ms&quot;
236  checks_failed=$((checks_failed + 1))
237  failures=&quot;${failures}  - $name: response time ${response_time}ms (max ${max_response_time_ms}ms)\n&quot;
238fi
239```
240 
241---
242 
243## Reference block 5
244 
245```bash
246total=$((checks_passed + checks_failed))
247echo &quot;&quot;
248echo &quot;=== Smoke Test Summary ===&quot;
249echo &quot;Total: $total | Passed: $checks_passed | Failed: $checks_failed&quot;
250
251if [ &quot;$checks_failed&quot; -gt 0 ]; then
252  echo &quot;&quot;
253  echo &quot;Failures:&quot;
254  echo -e &quot;$failures&quot;
255  exit 1
256else
257  echo &quot;All checks passed.&quot;
258  exit 0
259fi
260```
261