Deploy-Gated Testing

About

How to configure deploy-gated tests in catalog-info.yaml (catalog version 0.5.0+). Covers smoke test configuration (HTTP GET probes with expected status codes), the test execution flow via iec-test, retry logic with exponential backoff, environment-specific behavior (prod vs sandbox), and how to view test results in build logs.

Skill Content

This is the raw markdown that gets installed as a Claude Code rule.

# Deploy-Gated Testing

## What this skill covers
How to configure and use deploy-gated tests that run automatically after deployment on the Tawa platform.

## Overview

Deploy-gated tests run AFTER your service is deployed to Kubernetes but BEFORE the build is marked as completed. If tests fail, the build status is `failed` — but the deployment is NOT rolled back. The pod stays running for debugging.

This is distinct from unit/integration tests (which run during development). Deploy-gated tests validate that a deployed service is actually responding correctly.

## Requirements

- Catalog version 0.5.0: `insureco.io/catalog-version: "0.5.0"`
- `IEC_TEST_URL` configured on the builder (already set in production)

## Configuring Smoke Tests

Add `spec.tests` to your `catalog-info.yaml`:

```yaml
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: my-service
  description: My service
  annotations:
    insureco.io/framework: express
    insureco.io/catalog-version: "0.5.0"
    insureco.io/health-endpoint: /health
spec:
  type: service
  lifecycle: production
  owner: my-org
  tests:
    smoke:
      - path: /health
        expect: 200
      - path: /api/ping
        expect: 200
```

### Smoke Test Fields

| Field | Required | Description |
|-------|----------|-------------|
| `path` | Yes | HTTP GET endpoint path (e.g., `/health`) |
| `expect` | Yes | Expected HTTP status code (e.g., `200`) |

## How It Works

1. Builder deploys service via Helm
2. Builder configures DNS (Cloudflare CNAME)
3. Builder verifies pods are healthy
4. Builder POSTs test specs to iec-test service
5. iec-test executes HTTP GET probes against the internal cluster URL
6. Each probe retries up to 5 times with exponential backoff (2s, 4s, 8s, 16s, 32s)
7. Builder polls iec-test every 5 seconds for results (10 minute timeout)
8. If all tests pass → build completes. If any fail → build marked `failed`.

## Environment Behavior

| Environment | Test Suites |
|-------------|------------|
| sandbox | smoke + e2e |
| uat | smoke + e2e |
| prod | smoke only |

## Viewing Test Results

```bash
# Check build status
tawa status --build <build-id>

# View full build logs including test results
tawa logs --build <build-id>
```

Example log output:
```
Deployed to Kubernetes namespace: my-service-prod
DNS configured: my-service.tawa.insureco.io -> 137.184.244.227
[post-deploy] All pods healthy
Running deploy-gated tests...
Test result: smoke: passed (2/2)
Build completed successfully
```

## Key Facts

- Tests use the internal K8s cluster URL, not the external hostname (avoids DNS propagation delays)
- Test failure does NOT roll back the deployment — the pod stays running
- Smoke tests are simple HTTP GET probes — no authentication headers are sent
- The `testing` build status appears between `deploying` and `completed`
- If `IEC_TEST_URL` is not set on the builder, testing is silently skipped

## Reference: tawa-smoke-canary

The `tawa-smoke-canary` service exists as a permanent canary to validate the testing pipeline. It has two smoke checks (/health and /api/ping) and no other dependencies.

Install

Copy the skill content and save it to:

~/.claude/rules/deploy-gated-testing.md

Details

Format

Rule

Category

deploy

Version

1.0.0

Tokens

~900

Updated

2026-02-24