skills.rest
civitas-cerebrum
civitas-cerebrumOFFICIAL
Explore all skills by this author →
GitHub

contract-testing

Writes contract-style API tests asserting status codes, headers, and response schemas with Playwright.

5|2|Updated May 19, 2026
Search Tags:#test automation#openapi#qa#playwright#api testing#contract testing#schema validation
One-click install
npx skills add https://github.com/civitas-cerebrum/achilles --skill contract-testing-civitas-cerebrum
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: contract-testing
Source: https://github.com/civitas-cerebrum/achilles/tree/main/skills/contract-testing
Command: npx skills add https://github.com/civitas-cerebrum/achilles --skill contract-testing-civitas-cerebrum

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill requires @civitas-cerebrum/element-interactions, @playwright/test.

What problem does it solve? Backend API regressions slip into production when tests only cover UI flows or assert nothing about response shape. This Skill enforces a structured protocol for locking the contract between clients and HTTP services — status codes, headers, response schemas, and error envelopes — so breaking changes are caught before they reach the UI. ## Core Features & Use Cases - Contract Inventory & Test Design: Enumerates per-endpoint obligations (status, content-type, happy-path shape, error shape, auth shape) from an OpenAPI spec or confirmed live responses, with one obligation per test. - Canonical Implementation Patterns: Provides copy-ready patterns using the Steps API (steps.apiGet/Post/Put/Delete/Patch/Head, verifyApiStatus, verifyApiHeader) with typed responses, shared schema files, multi-provider routing, and a dedicated playwright.contracts.config.ts. - Deliberate-Failure Verification: Mandates a mutation check (flip a schema field or status expectation, confirm tests fail, revert) before any report ships, proving the suite actually bites. - Use Case: A team consuming a staging GET /users/:id endpoint uses this Skill to generate tests asserting 200 status, JSON content-type, a UserSchema shape, and 404/401 error envelopes — catching a backend field rename the day it lands. ## Quick Start Ask the agent to write contract tests for your staging API endpoints, for example: "Write contract tests for GET /users/:id and POST /users against our staging backend."

Frequently Asked Questions about contract-testing

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I write API contract tests with Playwright?▼

Use the Steps API methods steps.apiGet/apiPost with typed responses, then assert status via verifyApiStatus, headers via verifyApiHeader, and body shape with expect(res.body).toMatchObject(schema). Place tests under tests/contracts/ with a dedicated playwright.contracts.config.ts.

What is the difference between contract-style tests and Pact contract testing?▼

Contract-style tests assert status, schema, and error shape against a live endpoint directly. Pact uses a broker to generate and verify pact files between consumer and provider. This framework does not produce pact files; use Pact if you need broker-based consumer-driven contracts.

Can I run contract tests against a mocked API?▼

No. Contract tests must hit a real staging, sandbox, or local endpoint because mocking defeats the purpose of detecting actual contract drift. If no endpoint is reachable, the workflow stops and asks you for an environment URL.

Why should contract tests assert shape instead of exact values?▼

Asserting exact values like id === 42 breaks when seed data changes, producing churn unrelated to the contract. Shape assertions like expect.any(Number) fail only when the API contract itself changes, keeping failures meaningful.

How do I test multiple backend APIs in one test suite?▼

Configure named providers via the apiProviders option on baseFixture, then call steps.apiGet('billing', '/invoices/1') with the provider name. This supports cross-service checks, such as verifying an invoice references a real auth user.

Why do contract tests need a deliberate-failure check?▼

A suite that passes on first run may contain vacuous assertions that never fail. Mutating one schema field or status expectation and confirming the tests fail proves the assertions actually bite before the results are reported.

Related Skills

Explore More Software Engineering Skills→
growthxaigrowthxai
430

output-credentials-env-vars

Resolve credential: references into environment variables at worker startup.

Official
Intermediate
endorlabsendorlabs
4

endor-troubleshoot-sdk

Diagnose Endor Labs SDK failures by comparing client behavior with endorctl and OpenAPI contracts.

Official
Advanced
paulinett1508-devpaulinett1508-dev

integration-testing

Execute API and database integration tests in isolated, reproducible environments.

Community
Intermediate
Prathmesh2000Prathmesh2000
1

api-contract-tester

Implement consumer-driven contract testing with Pact and a Pact Broker.

Community
Advanced