agentleFS
alex-voloshin-devalex-voloshin-dev/ai-skills/.agents/skills/test-local/SKILL.md

test-local

Skill2 starsChanged 6 months agoMITView on GitHub

Local dev testing workflow — verify test environment, provision infrastructure (Docker, Testcontainers), run multi-level test suite (unit → integration → E2E), coverage analysis, quality gate. Applies QA Engineer role. Use for full local QA cycle before commit or PR.

  • Reads credentials
  • Installs packages

2 other projects use a version of this.

Adopted by

Most recently taken up by

The file

Show its rules and text

We split this skill into the rules it gives an agent

24 rules. About 0 are common, 19 are distinctive, and 5 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈19

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 5

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Read TESTING.md at the project root (and per-service TESTING.md in monorepos) for test infrastructure, commands, credentials, and …

    line 24
  2. Distinctive:

    Ask the user (or extract from context):

    line 26
  3. Distinctive:

    If invoked by another workflow — extract scope from parent context.

    line 32
  4. Distinctive:

    Read AGENTS.md and scan project files to determine:

    line 49
  5. Distinctive:

    Before running tests, verify the local environment is ready.

    line 68
  6. Distinctive:

    If Docker is not running — notify user and stop.

    line 77
  7. Distinctive:

    Check that ports needed by test services are available:

    line 81
  8. Distinctive:

    If conflicts found — report which process holds the port.

    line 90
  9. Distinctive:

    Check for test-specific environment configuration:

    line 94
  10. Very specific:

    Read only .env.example for reference — never log or output actual .env values

    line 98
  11. Distinctive:

    Verify project dependencies are installed:

    line 102
  12. Very specific:

    If dependencies are stale — suggest npm install / pip install -r requirements.txt / etc.

    line 111
  13. Distinctive:

    If the project uses Testcontainers — no manual setup needed.

    line 119
  14. Very specific:

    If the project uses docker-compose.test.yml or similar:

    line 127
  15. Distinctive:

    Wait for services to be healthy:

    line 133
  16. Very specific:

    Check health status. If any service is unhealthy — collect logs and diagnose using devops-engineer role.

    line 139
  17. Distinctive:

    If the project has seed scripts for test data:

    line 143
  18. Distinctive:

    Run seed scripts after infrastructure is ready

    line 146
  19. Distinctive:

    Verify seed completed successfully

    line 147
  20. Distinctive:

    If the project uses only mocks/stubs for unit tests — skip to Step 6.

    line 151
  21. Distinctive:

    Run only if unit tests pass (or user explicitly requested):

    line 170
  22. Distinctive:

    Run only if integration tests pass (or user explicitly requested):

    line 189
  23. Distinctive:

    If user requested or project has them:

    line 210
  24. Distinctive:

    After all tests pass, run coverage analysis:

    line 220

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Test Local

Full QA cycle for local development environments. Verifies test infrastructure, provisions dependencies, runs tests at all levels (unit → integration → E2E), analyzes coverage, and applies quality gates. Orchestrated by qa-engineer role.

Key difference from run-tests skill: This workflow manages the full local test environment lifecycle (setup → test → report → cleanup). run-tests skill is a lightweight follow-up skill that only executes and analyzes tests.

1. Define Scope

Read TESTING.md at the project root (and per-service TESTING.md in monorepos) for test infrastructure, commands, credentials, and organization. This is the authoritative source for how to test the project.

Ask the user (or extract from context):

  • Test scope: Full suite / specific module / specific test level (unit / integration / E2E)
  • What changed: New feature / bug fix / refactor / pre-commit check / full regression
  • Known issues: Any tests expected to fail? Any infra known to be down?

If invoked by another workflow — extract scope from parent context.

2. Apply Roles

Primary: qa-engineer role — owns test strategy, quality gates, and test infrastructure decisions.

Secondary (applied as needed during test execution):

NeedRole
Fix failing unit/integration testsStack-specific: java-engineer role / python-engineer role / frontend-engineer role
Docker/compose/infra issuesdevops-engineer role
Test data / database schemadb-engineer role
General debuggingsoftware-engineer role

3. Detect Project Stack

Read AGENTS.md and scan project files to determine:

SignalStackTest RunnerContainer Tool
package.json + vitest/jestTypeScript/JSnpx vitest / npx jestTestcontainers-node
package.json + playwrightTypeScript/JS (E2E)npx playwright testPlaywright containers
pom.xml / build.gradleJavamvn test / gradle testTestcontainers-java
pyproject.toml / pytest.iniPythonpytestTestcontainers-python
go.modGogo test ./...Testcontainers-go
*.csproj.NETdotnet testTestcontainers-dotnet

Also detect:

  • Docker Compose: docker-compose.yml, docker-compose.test.yml, compose.yaml
  • Test config files: .env.test, jest.config.*, vitest.config.*, playwright.config.*, pytest.ini, conftest.py
  • CI config: .github/workflows/, Jenkinsfile, .gitlab-ci.yml — extract test commands used in CI for parity

4. Verify Local Environment

Before running tests, verify the local environment is ready.

4a. Docker Daemon

// turbo
docker version --format "Client: {{.Client.Version}} | Server: {{.Server.Version}}"

If Docker is not running — notify user and stop. Tests requiring containers will fail.

4b. Port Conflicts

Check that ports needed by test services are available:

// turbo
netstat -ano | findstr ":<port>"

Common test ports: 5432 (PostgreSQL), 6379 (Redis), 27017 (MongoDB), 9092 (Kafka), 3306 (MySQL).

If conflicts found — report which process holds the port. Suggest resolution.

4c. Environment Variables

Check for test-specific environment configuration:

  • Root .env — verify it exists and contains test_ prefixed variables (e.g., test_user, test_db_host)
  • Compare with .env.example — flag missing test variables
  • Read only .env.example for reference — never log or output actual .env values

4d. Dependencies

Verify project dependencies are installed:

StackCheck Command
Node.jsnode_modules/ exists, package-lock.json up to date
Javamvn dependency:resolve -q
PythonVirtual env active, pip check
Gogo mod verify

If dependencies are stale — suggest npm install / pip install -r requirements.txt / etc.

5. Provision Test Infrastructure

Based on project config, set up test dependencies.

5a. Testcontainers (preferred)

If the project uses Testcontainers — no manual setup needed. Testcontainers starts/stops containers automatically per test suite. Verify:

  • Docker daemon is running (Step 4a)
  • Testcontainers config exists (.testcontainers.properties if needed)
  • Required images are available (or will be pulled automatically)

5b. Docker Compose

If the project uses docker-compose.test.yml or similar:

docker compose -f docker-compose.test.yml up -d

Wait for services to be healthy:

docker compose -f docker-compose.test.yml ps

Check health status. If any service is unhealthy — collect logs and diagnose using devops-engineer role.

5c. Seed Data

If the project has seed scripts for test data:

  1. Locate seed scripts (check AGENTS.md, package.json scripts, Makefile, scripts/ directory)
  2. Run seed scripts after infrastructure is ready
  3. Verify seed completed successfully

5d. No Infrastructure Needed

If the project uses only mocks/stubs for unit tests — skip to Step 6.

6. Run Tests

Execute tests in pyramid order: unit → integration → E2E. Stop at first failing level unless user requested full suite.

6a. Unit Tests

// turbo
<unit-test-command>

Expected: Fast (< 2 min), high pass rate. If unit tests fail — fix before proceeding.

For failures — delegate to run-tests skill for analysis and auto-fix (Step 3-4 of that workflow).

6b. Integration Tests

Run only if unit tests pass (or user explicitly requested):

<integration-test-command>

Expected: Moderate speed (< 10 min). Tests interact with real dependencies (DB, APIs via containers).

Common integration test patterns by stack:

StackCommandNotes
Vitest/Jestnpx vitest run --project integrationIf workspace configured
pytestpytest tests/integration/ -vOr pytest -m integration
Mavenmvn verify -pl <module>Failsafe plugin for ITs
Gogo test -tags=integration ./...Build tag separation

6c. E2E Tests

Run only if integration tests pass (or user explicitly requested):

<e2e-test-command>

Prerequisites:

  • Application must be running locally (dev server or Docker)
  • E2E test config must point to local URL
  • Browser binaries installed (Playwright: npx playwright install)

Common E2E commands:

StackCommand
Playwrightnpx playwright test
Cypressnpx cypress run
pytest + Seleniumpytest tests/e2e/ -v

6d. Specialized Tests (optional)

If user requested or project has them:

TypeWhenCommand Pattern
PerformancePre-release, after optimizationk6 run tests/load/script.js
SecurityPre-release, after auth changesnpm audit / OWASP ZAP scan
AccessibilityUI changesnpx playwright test --grep @a11y or axe-core

7. Coverage Analysis

After all tests pass, run coverage analysis:

StackCommand
Vitestnpx vitest run --coverage
Jestnpx jest --coverage
pytestpytest --cov=<package> --cov-report=term-missing
Gogo test -coverprofile=coverage.out ./... && go tool cover -func=coverage.out
Mavenmvn jacoco:report

Compare against test-strategy skill targets:

MetricTargetHard MinimumStatus
Line coverage≥ 80%≥ 60%[pass/fail]
Branch coverage≥ 75%≥ 50%[pass/fail]
New code coverage≥ 90%≥ 80%[pass/fail]

Flag modules with coverage below hard minimum.

8. Quality Gate

Evaluate overall test quality:

GateCriteriaResult
Unit testsAll pass✅ / ❌
Integration testsAll pass (if run)✅ / ❌ / ⏭️ skipped
E2E testsAll pass (if run)✅ / ❌ / ⏭️ skipped
CoverageMeets targets✅ / ⚠️ below target / ❌ below minimum
No flaky testsZero retried tests✅ / ⚠️
No new warningsLint + type checks clean✅ / ❌

Decision:

ResultAction
All gates pass✅ PASS — safe to commit/PR
Coverage warning only⚠️ PASS with notes — consider adding tests
Any test failure❌ FAIL — fix before commit
Flaky tests detected⚠️ PASS with action — file flaky test issue

9. Cleanup

After testing completes:

  1. Stop test containers (if Docker Compose was used):
    docker compose -f docker-compose.test.yml down -v
  2. Remove test data (if seed scripts ran outside containers)
  3. Report leftover containers (if any test containers weren't cleaned up)

Testcontainers handles its own cleanup automatically — verify no orphaned containers remain.

10. Summary

## Local Test Summary

### Environment
- **Stack**: [detected stack]
- **Docker**: [version] | Test infra: [Testcontainers / Docker Compose / none]
- **Env issues**: [none / list]

### Test Results
| Level | Total | Passed | Failed | Skipped | Duration |
|-------|-------|--------|--------|---------|----------|
| Unit | X | X | X | X | Xs |
| Integration | X | X | X | X | Xs |
| E2E | X | X | X | X | Xs |

### Coverage
| Metric | Value | Target | Status |
|--------|-------|--------|--------|
| Line | X% | 80% | ✅/❌ |
| Branch | X% | 75% | ✅/❌ |
| New code | X% | 90% | ✅/❌ |

### Coverage Gaps
- [file/module] — [current%] — [uncovered areas]

### Quality Gate: ✅ PASS / ❌ FAIL
- [gate details]

### Failures Fixed (if any)
- [test] — [issue] — [fix]

### Remaining Issues
- [issue] — [action needed]

### Follow-up
- [recommendations]

Integration

  • Roles: qa-engineer role (primary), stack-specific roles (test fixes), devops-engineer role (infra issues)
  • Skills: test-strategy skill (test patterns, coverage targets)
  • follow-up skills: run-tests skill (test execution and auto-fix for failures)
  • Called by: feature-dev skill (pre-commit testing), bugfix skill (verify fix)
  • Follow-up: pre-commit skill (quality gate), create-pr skill (submit changes)

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.