playbooks

home / skills / laurigates / claude-plugins / skaffold-testing

skaffold-testing skill

/container-plugin/skills/skaffold-testing

This skill helps validate Skaffold pipelines with container-structure-tests and tests for pre-deploy and post-deploy verification, ensuring image hygiene.

npx playbooks add skill laurigates/claude-plugins --skill skaffold-testing

Review the files below or copy the command above to add this skill to your agents.

Files (2)
skill.md
4.9 KB
---
model: haiku
name: skaffold-testing
description: |
  Container image validation with Skaffold test and verify stages. Covers container-structure-tests
  for image hygiene, custom tests for security scanning, and post-deployment verification.
  Use when configuring pre-deploy tests, security scans, or integration tests in Skaffold pipelines.
allowed-tools: Bash, Read, Write, Edit, Grep, Glob, TodoWrite
created: 2025-12-23
modified: 2026-02-14
reviewed: 2025-12-23
---

# Skaffold Testing

## When to Use This Skill

| Use this skill when... | Use another skill instead when... |
|------------------------|-----------------------------------|
| Configuring container-structure-tests | Writing Dockerfiles (use container skills) |
| Adding security scans to Skaffold pipelines | General Skaffold build/deploy (use skaffold-development) |
| Setting up post-deploy verification | Unit testing application code |
| Validating image contents pre-deploy | Kubernetes manifest authoring |

## Testing Lifecycle

```
Build -> Test -> Deploy -> Verify
          ^                  ^
     Pre-deploy         Post-deploy
```

| Stage | Purpose | Runs During |
|-------|---------|-------------|
| **test** | Validate images before deployment | `dev`, `run`, `test` |
| **verify** | Validate deployment works correctly | `dev`, `run`, `verify` |

Failed tests block deployment. Use `--skip-tests` to bypass.

## Test Stage Overview

Two mechanisms for pre-deploy validation:

| Type | Purpose | Tool Required |
|------|---------|---------------|
| **structureTests** | Validate image contents | `container-structure-test` binary |
| **custom** | Run arbitrary commands | None (uses `$IMAGE` env var) |

## Container Structure Tests

Validate image contents without running the container.

### Configuration

```yaml
apiVersion: skaffold/v4beta11
kind: Config
test:
  - image: my-app
    structureTests:
      - ./tests/structure/*.yaml
    structureTestsArgs:
      - --driver=tar      # Faster, no Docker daemon needed
      - -q                # Quiet output
```

### Test Types Summary

| Type | Purpose | Key Fields |
|------|---------|------------|
| **commandTests** | Verify binaries work | `command`, `args`, `expectedOutput`, `exitCode` |
| **fileExistenceTests** | Verify files present/absent | `path`, `shouldExist`, `permissions`, `uid`, `gid` |
| **fileContentTests** | Validate file contents | `path`, `expectedContents`, `excludedContents` |
| **metadataTest** | Validate image config | `envVars`, `user`, `entrypoint`, `cmd`, `exposedPorts`, `workdir` |

## Custom Tests

Run arbitrary commands with access to built image via `$IMAGE` env var.

```yaml
test:
  - image: my-app
    custom:
      - command: grype $IMAGE --fail-on high --only-fixed
        timeoutSeconds: 300
      - command: trivy image --exit-code 1 --severity HIGH,CRITICAL $IMAGE
        timeoutSeconds: 300
```

### Dependencies

Control when tests re-run:

```yaml
custom:
  - command: ./scripts/integration-test.sh
    timeoutSeconds: 600
    dependencies:
      paths:
        - "src/**/*.go"
        - "go.mod"
      ignore:
        - "**/*_test.go"
```

## Verify Stage (Post-Deploy)

Run integration tests after deployment succeeds.

### Execution Modes

| Mode | Environment | Use Case |
|------|-------------|----------|
| `local` (default) | Docker on host | Quick tests, local dev |
| `kubernetesCluster` | K8s Job | Integration tests needing cluster access |

### Basic Configuration

```yaml
verify:
  - name: health-check
    container:
      name: curl-test
      image: curlimages/curl:latest
      command: ["/bin/sh"]
      args: ["-c", "curl -f http://my-app.default.svc:8080/health"]
    executionMode:
      kubernetesCluster: {}
```

## Agentic Optimizations

| Context | Command |
|---------|---------|
| Quick structure test | `container-structure-test test --driver=tar -q --image $IMAGE --config tests/structure/security.yaml` |
| Security scan (critical only) | `grype $IMAGE --fail-on critical -q` |
| Skip tests in dev | `skaffold dev --skip-tests` |
| Run only tests | `skaffold test` |
| Run only verify | `skaffold verify` |
| CI with JUnit output | `container-structure-test test --image $IMAGE --config test.yaml --test-report junit.xml` |

## Quick Reference

### Container Structure Test Flags

| Flag | Description |
|------|-------------|
| `--driver=tar` | Use tar driver (faster, no Docker daemon) |
| `--driver=docker` | Use Docker driver (default) |
| `-q` | Quiet output |
| `--test-report FILE` | Generate test report |
| `--output json` | JSON output format |

### Skaffold Test Flags

| Flag | Description |
|------|-------------|
| `--skip-tests` | Skip test phase |
| `-p PROFILE` | Use specific profile |
| `--build-artifacts FILE` | Use pre-built artifacts |

### Custom Test Environment

| Variable | Description |
|----------|-------------|
| `$IMAGE` | Built image with tag/digest |

For detailed examples, advanced patterns, and best practices, see [REFERENCE.md](REFERENCE.md).

Overview

This skill provides container image validation and post-deployment verification using Skaffold's test and verify stages. It covers container-structure-tests for image hygiene, custom command tests for security scanning, and verify jobs for post-deploy integration checks. Use it to block unsafe images from deploying and to validate runtime behavior after deployment.

How this skill works

Pre-deploy tests run in the Skaffold test stage and can be either container-structure-tests (declarative checks against image contents) or custom commands that receive the built image via the $IMAGE environment variable. Failed tests prevent deployment unless you pass --skip-tests. Post-deploy verification runs in the verify stage as either local container commands or Kubernetes jobs to validate the live deployment.

When to use it

  • Validating image contents and metadata before deployment
  • Adding security scanners (Trivy, Grype) into Skaffold pipelines
  • Blocking deployment on failed image hygiene or security checks
  • Running integration or health checks after a deployment succeeds
  • Re-running only tests or verify stages in CI with skaffold test / skaffold verify

Best practices

  • Prefer container-structure-tests for fast, reproducible image assertions without running containers
  • Use --driver=tar for CI to avoid needing a Docker daemon and speed execution
  • Run security scanners as custom tests referencing $IMAGE and set appropriate timeouts
  • Add file and metadata checks (UID, permissions, env vars, entrypoint) to catch packaging regressions
  • Use verify stage with kubernetesCluster for real cluster integration tests and local mode for quick developer checks

Example use cases

  • Pre-deploy: fileExistenceTests ensure configuration files and binaries are present and correct
  • Security: custom tests run Grype or Trivy against $IMAGE and fail build on high/critical findings
  • CI: run container-structure-test with --test-report junit.xml to integrate results into CI dashboards
  • Post-deploy: verify stage runs a curl container as a Kubernetes Job to assert application health endpoints
  • Local dev: skaffold dev --skip-tests to iterate quickly, or skaffold test to run only validation before deploying

FAQ

What happens if a test fails?

A failing test blocks deployment by default. Use --skip-tests to bypass in development, but avoid skipping in CI.

Do custom tests need additional tools inside Skaffold?

No. Custom tests run arbitrary shell commands and receive the built image in $IMAGE. Install scanners (grype, trivy) in the environment where Skaffold runs.