Files
skills/public/testing-integration-testing.html
zeekay 747dafba10 Register WebMCP tools on every page, and name each page's twin from site.py
Every page now loads /webmcp.js, scripts/webmcp.ts with its types
stripped (npm run webmcp). Where the browser has document.modelContext
it registers two read-only tools: search_skills over the published
skills index, and get_skill, which returns a skill's markdown checked
against the index digest. The markdown alternate link moves from
build.py to site.py, so CI holds every page to it.

The API catalog gains the site itself (llms.txt and the skills index)
and hanzo.ai/agents; the live discovery check now fetches every
catalog link. tests/site.mjs drives the tools through a recording
modelContext, and checks a browser without one loads clean.
2026-10-26 20:57:05 -07:00

823 lines
37 KiB
HTML

<!doctype html>
<html lang="en"><head>
<meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
<title>testing-integration-testing</title>
<meta name="color-scheme" content="dark">
<style>
/* Committed to one visual world: a dark instrument panel. No light variant —
the dot field and the hairline rules only read on black, and a naive
inversion would wash both out. Every colour is painted explicitly so the page
never borrows a host background. */
@font-face{font-family:'Zen';src:url('/fonts/Zen-Variable.woff2') format('woff2');font-weight:100 900;font-style:normal;font-display:swap}
@font-face{font-family:'Zen';src:url('/fonts/Zen-Italic-Variable.woff2') format('woff2');font-weight:100 900;font-style:italic;font-display:swap}
@font-face{font-family:'Zen Mono';src:url('/fonts/ZenMono-Variable.woff2') format('woff2');font-weight:100 900;font-style:normal;font-display:swap}
@font-face{font-family:'Zen Mono';src:url('/fonts/ZenMono-Italic-Variable.woff2') format('woff2');font-weight:100 900;font-style:italic;font-display:swap}
@font-face{font-family:'Zen Pixel Square';src:url('/fonts/ZenPixel-Square.woff2') format('woff2');font-style:normal;font-display:swap}
:root{
--ink:#f4f4f2; --soft:#9c9c98; --faint:#6a6a66; --ground:#000; --panel:#0a0a0a;
--line:#232323; --line-hi:#3a3a3a; --accent:#f4f4f2;
--font-zen-sans:'Zen',-apple-system,BlinkMacSystemFont,"Segoe UI",Helvetica,Arial,sans-serif;
--font-zen-mono:'Zen Mono',ui-monospace,"SF Mono",SFMono-Regular,Menlo,Consolas,monospace;
--font-zen-pixel-square:'Zen Pixel Square',monospace;
--mono:var(--font-zen-mono);
--sans:var(--font-zen-sans);
/* Controls are pills and surfaces are soft, as on hanzo.ai. */
--r:999px; --r-soft:14px;
}
*{box-sizing:border-box}
html{-webkit-text-size-adjust:100%}
body{margin:0;background:var(--ground);color:var(--ink);font-family:var(--sans);
font-size:16px;line-height:1.65;-webkit-font-smoothing:antialiased}
.wrap{max-width:60rem;margin:0 auto;padding:0 1.75rem}
/* The dot field. A halftone made of one repeating radial-gradient, faded out
along the diagonal by a mask so it reads as a wave rather than wallpaper. */
/* No overflow clip here: the dot field is inset to the box already, and a clip
would cut off the copy-prompt menu. */
.hero{position:relative;border-bottom:1px solid var(--line)}
.hero::before{content:"";position:absolute;inset:0;
background-image:radial-gradient(var(--line-hi) 1px, transparent 1px);
background-size:7px 7px;
-webkit-mask-image:linear-gradient(115deg,#000 0%,rgba(0,0,0,.55) 38%,transparent 72%);
mask-image:linear-gradient(115deg,#000 0%,rgba(0,0,0,.55) 38%,transparent 72%);
pointer-events:none}
.hero .wrap{position:relative;padding-top:5.5rem;padding-bottom:4rem}
nav{border-bottom:1px solid var(--line)}
nav .in{max-width:60rem;margin:0 auto;padding:1.1rem 1.75rem;display:flex;
justify-content:space-between;align-items:center;gap:1rem}
.brand{font-family:var(--mono);font-size:.85rem;letter-spacing:.14em;
text-transform:uppercase;color:var(--ink);text-decoration:none;
display:inline-flex;align-items:center;gap:.6rem}
.brand i{font-style:normal;color:var(--faint)}
.mark{width:1.15em;height:1.15em;display:block;flex:0 0 auto}
nav a.up{font-family:var(--mono);font-size:.72rem;letter-spacing:.14em;
text-transform:uppercase;color:var(--soft);text-decoration:none}
nav a.up:hover{color:var(--ink)}
h1{font-family:var(--mono);font-size:clamp(2rem,5.4vw,3.4rem);line-height:1.12;
letter-spacing:-.02em;margin:0 0 1.1rem;font-weight:500;text-wrap:balance}
h1 em{font-style:normal;color:var(--faint)}
.lede{color:var(--soft);font-size:1.05rem;max-width:52ch;margin:0 0 2.25rem}
.btns{display:flex;flex-wrap:wrap;gap:.7rem;margin:0 0 .5rem;align-items:center}
.btn{display:inline-flex;align-items:center;gap:.5rem;font-family:var(--mono);
font-size:.72rem;letter-spacing:.14em;text-transform:uppercase;
padding:.8rem 1.4rem;border:1px solid var(--line-hi);border-radius:var(--r);
color:var(--ink);text-decoration:none;background:transparent;cursor:pointer;
line-height:1.2;font-weight:400}
.btn:hover{background:#141414;text-decoration:none;border-color:var(--soft)}
.btn.solid{background:var(--ink);color:#000;border-color:var(--ink)}
.btn.solid:hover{background:#d8d8d4}
.btn .chev{width:.7em;height:.7em;flex:0 0 auto;transition:transform .15s ease}
.btn[aria-expanded="true"] .chev{transform:rotate(180deg)}
/* Copy-prompt selector. Each row copies the prompt for its own target. */
.copy{position:relative;display:inline-flex}
.menu{position:absolute;top:calc(100% + .5rem);left:0;z-index:20;min-width:21rem;
background:var(--panel);border:1px solid var(--line-hi);border-radius:var(--r-soft);
padding:.4rem;display:flex;flex-direction:column;
box-shadow:0 12px 32px rgba(0,0,0,.75)}
.menu[hidden]{display:none}
.mi{display:flex;align-items:center;gap:.7rem;width:100%;text-align:left;
padding:.62rem .8rem;border:0;border-radius:calc(var(--r-soft) - .35rem);
background:transparent;color:var(--ink);font-family:var(--mono);font-size:.76rem;
letter-spacing:.04em;text-decoration:none;cursor:pointer;line-height:1.3;
white-space:nowrap}
.mi:hover,.mi:focus-visible{background:#181818;outline:none}
.mi .mark{width:1.05rem;height:1.05rem;color:var(--soft)}
.mi:hover .mark{color:var(--ink)}
.mi u{margin-left:auto;color:var(--faint);text-decoration:none;font-size:.68rem;
letter-spacing:.1em;text-transform:uppercase}
/* Works-with bar: one scrolling row, name and mark per agent. */
.strip{border-bottom:1px solid var(--line);background:var(--panel)}
.strip .in{max-width:60rem;margin:0 auto;padding:.9rem 1.75rem;display:flex;
align-items:center;gap:1.25rem;font-family:var(--mono);font-size:.72rem;
letter-spacing:.1em;text-transform:uppercase;color:var(--faint)}
.strip b{color:var(--soft);font-weight:400;flex:0 0 auto;
border-right:1px solid var(--line);padding-right:1.25rem;align-self:stretch;
display:flex;align-items:center}
.bar{display:flex;align-items:center;gap:.5rem;flex:1 1 auto;min-width:0;
overflow-x:auto;scrollbar-width:none;scroll-snap-type:x proximity;
-webkit-overflow-scrolling:touch;
-webkit-mask-image:linear-gradient(90deg,#000 calc(100% - 3rem),transparent);
mask-image:linear-gradient(90deg,#000 calc(100% - 3rem),transparent)}
.bar::-webkit-scrollbar{display:none}
.agent{display:inline-flex;align-items:center;gap:.45rem;flex:0 0 auto;
padding:.4rem .85rem;border:1px solid var(--line);border-radius:var(--r);
color:var(--soft);white-space:nowrap;scroll-snap-align:start;
text-decoration:none;background:var(--ground)}
.agent:hover{color:var(--ink);border-color:var(--line-hi);text-decoration:none}
.agent .mark{width:.95rem;height:.95rem}
h2{font-family:var(--mono);font-size:1.1rem;letter-spacing:-.01em;margin:2.75rem 0 .75rem;font-weight:500}
h3{font-size:1rem;margin:2rem 0 .5rem;font-weight:600}
h4,h5,h6{font-size:.94rem;margin:1.5rem 0 .5rem;font-weight:600}
p{margin:0 0 1rem;max-width:70ch}
ul,ol{margin:0 0 1rem;padding-left:1.35rem;max-width:70ch}
li{margin:.22rem 0}
a{color:var(--ink);text-decoration:underline;text-underline-offset:3px;
text-decoration-color:var(--line-hi)}
a:hover{text-decoration-color:var(--ink)}
a:focus-visible{outline:1px solid var(--ink);outline-offset:3px}
code{font-family:var(--mono);font-size:.85em;background:var(--panel);
border:1px solid var(--line);border-radius:5px;padding:.1em .36em}
pre{background:var(--panel);border:1px solid var(--line);padding:1rem 1.1rem;
border-radius:var(--r-soft);overflow-x:auto;margin:0 0 1.25rem}
pre code{background:none;border:0;padding:0;font-size:.82rem;line-height:1.7}
blockquote{margin:0 0 1rem;padding-left:1rem;border-left:1px solid var(--line-hi);color:var(--soft)}
hr{border:0;border-top:1px solid var(--line);margin:2.5rem 0}
table{border-collapse:collapse;width:100%;margin:0 0 1.25rem;font-size:.92rem;
display:block;overflow-x:auto}
th,td{border:1px solid var(--line);padding:.5rem .7rem;text-align:left}
.curl{display:block;background:var(--panel);border:1px solid var(--line);
border-radius:var(--r-soft);padding:.95rem 1.1rem;font-family:var(--mono);
font-size:.8rem;color:var(--soft);overflow-x:auto;margin:0 0 2.5rem;
white-space:pre;line-height:1.9}
.curl b{color:var(--ink);font-weight:400}
.curl i{font-style:normal;color:var(--faint)}
/* index */
#q{width:100%;padding:.85rem 1.2rem;font-family:var(--mono);font-size:.85rem;color:var(--ink);
background:var(--panel);border:1px solid var(--line);border-radius:var(--r);margin:0 0 .6rem}
#q::placeholder{color:var(--faint);text-transform:uppercase;letter-spacing:.1em;font-size:.72rem}
#q:focus{outline:none;border-color:var(--soft)}
#count{color:var(--faint);font-family:var(--mono);font-size:.72rem;letter-spacing:.1em;
text-transform:uppercase;margin:0 0 2rem}
.cat{margin:2.5rem 0 .5rem;font-family:var(--mono);font-size:.7rem;letter-spacing:.16em;
text-transform:uppercase;color:var(--faint);border-bottom:1px solid var(--line);
padding-bottom:.45rem}
.row{display:block;padding:.6rem .9rem;margin:0 -.9rem;border-bottom:1px solid var(--line);
border-radius:var(--r-soft);text-decoration:none}
.row:hover{background:#0a0a0a}
.nm{font-family:var(--mono);font-size:.84rem;color:var(--ink);display:block}
.ds{color:var(--soft);font-size:.9rem;display:block;margin-top:.12rem}
footer{margin-top:4rem;padding:2rem 0 4rem;border-top:1px solid var(--line);
color:var(--faint);font-size:.85rem}
footer a{color:var(--soft)}
.fmap{display:grid;gap:1.75rem;grid-template-columns:repeat(auto-fit,minmax(11rem,1fr));
margin:0 0 2rem;font-size:.85rem}
.fmap b{display:block;font-family:var(--mono);font-size:.68rem;letter-spacing:.16em;
text-transform:uppercase;color:var(--faint);font-weight:400;margin:0 0 .6rem;
border-bottom:1px solid var(--line);padding-bottom:.4rem}
.fmap a{display:inline-block;color:var(--ink);text-decoration:none;margin:.3rem .35rem 0 0}
.fmap a:hover{text-decoration:underline}
.fmap div{color:var(--faint);line-height:1.5}
.fend{border-top:1px solid var(--line);padding-top:1.25rem;font-size:.82rem}
@media (max-width:640px){
.hero .wrap{padding-top:3.25rem;padding-bottom:2.75rem}
.btns{gap:.5rem}
.btn{padding:.75rem 1.15rem;font-size:.68rem}
.copy,.copy .btn{width:100%;justify-content:center}
.menu{left:0;right:0;min-width:0}
.strip .in{flex-direction:column;align-items:flex-start;gap:.6rem;padding:.9rem 1.75rem}
.strip b{border-right:0;padding-right:0}
.bar{width:100%}
}
</style>
<link rel="icon" href="/favicon.svg">
<link rel="canonical" href="https://hanzoskills.com/testing-integration-testing">
<link rel="alternate" type="text/markdown" href="/testing-integration-testing.md">
<script type="module" src="/webmcp.js"></script>
</head>
<!-- Reading this with a machine? Every page here is also plain markdown.
This one: https://hanzoskills.com/testing-integration-testing.md
Index: https://hanzoskills.com/llms.txt
Corpus: https://hanzoskills.com/all.md
Append .md to any path for the markdown twin. -->
<body>
<nav><div class="in">
<a class="brand" href="/"><svg class="mark" viewBox="0 0 67 67" fill="currentColor" aria-hidden="true"><path d="M22.21 67V44.6369H0V67H22.21Z"/><path d="M66.7038 22.3184H22.2534L0.0878906 44.6367H44.4634L66.7038 22.3184Z"/><path d="M22.21 0H0V22.3184H22.21V0Z"/><path d="M66.7198 0H44.5098V22.3184H66.7198V0Z"/><path d="M66.7198 67V44.6369H44.5098V67H66.7198Z"/></svg> HANZO<i>SKILLS</i></a>
<a class="up" href="/">All skills</a>
</div></nav>
<div class="wrap">
<h1>testing-integration-testing</h1><p class="lede">Test interactions between multiple components or services</p><h1>Integration Testing</h1>
<h2>When to Use This Skill</h2>
<p>Use this skill when you need to:</p>
<ul><li>Test interactions between multiple components or services</li><li>Verify database operations (queries, transactions, migrations)</li><li>Test API endpoints with real HTTP requests</li><li>Use test containers for isolated infrastructure</li><li>Implement transaction rollback patterns for clean test state</li><li>Test message queues, caches, and external service integrations</li><li>Balance integration test coverage with speed and reliability</li></ul>
<p><strong>ACTIVATE THIS SKILL</strong>: When testing component interactions, databases, APIs, or external services</p>
<h2>Core Concepts</h2>
<h3>Integration Tests vs Unit Tests</h3>
<p><strong>Unit Tests</strong>:</p>
<ul><li>Single component in isolation</li><li>Fast (&lt; 100ms)</li><li>Mock all dependencies</li><li>Run thousands per second</li></ul>
<p><strong>Integration Tests</strong>:</p>
<ul><li>Multiple components together</li><li>Slower (100ms - 5s)</li><li>Real infrastructure (DB, cache, etc.)</li><li>Run hundreds per minute</li><li>Higher confidence in real behavior</li></ul>
<h3>Test Database Strategies</h3>
<p><strong>Strategy 1: In-Memory Database</strong> (SQLite)</p>
<pre><code class="lang-python"># Python (pytest)
import pytest
from sqlalchemy import create_engine
from myapp.models import Base
@pytest.fixture(scope=&quot;function&quot;)
def db_session():
engine = create_engine(&quot;sqlite:///:memory:&quot;)
Base.metadata.create_all(engine)
Session = sessionmaker(bind=engine)
session = Session()
yield session
session.close()
def test_create_user(db_session):
user = User(name=&quot;Alice&quot;, email=&quot;[email protected]&quot;)
db_session.add(user)
db_session.commit()
retrieved = db_session.query(User).filter_by(email=&quot;[email protected]&quot;).first()
assert retrieved.name == &quot;Alice&quot;</code></pre>
<p><strong>Strategy 2: Test Containers</strong> (Docker)</p>
<pre><code class="lang-python"># Python (testcontainers)
from testcontainers.postgres import PostgresContainer
import pytest
@pytest.fixture(scope=&quot;module&quot;)
def postgres_container():
with PostgresContainer(&quot;postgres:16&quot;) as postgres:
yield postgres
@pytest.fixture
def db_connection(postgres_container):
engine = create_engine(postgres_container.get_connection_url())
Base.metadata.create_all(engine)
connection = engine.connect()
yield connection
connection.close()
def test_user_repository(db_connection):
repo = UserRepository(db_connection)
user = repo.create(name=&quot;Alice&quot;, email=&quot;[email protected]&quot;)
assert repo.find_by_id(user.id).name == &quot;Alice&quot;</code></pre>
<pre><code class="lang-typescript">// TypeScript (testcontainers)
import { PostgreSqlContainer } from &#x27;@testcontainers/postgresql&#x27;;
import { DataSource } from &#x27;typeorm&#x27;;
describe(&#x27;UserRepository&#x27;, () =&gt; {
let container: PostgreSqlContainer;
let dataSource: DataSource;
beforeAll(async () =&gt; {
container = await new PostgreSqlContainer(&#x27;postgres:16&#x27;).start();
dataSource = new DataSource({
type: &#x27;postgres&#x27;,
host: container.getHost(),
port: container.getPort(),
username: container.getUsername(),
password: container.getPassword(),
database: container.getDatabase(),
entities: [User],
synchronize: true,
});
await dataSource.initialize();
});
afterAll(async () =&gt; {
await dataSource.destroy();
await container.stop();
});
it(&#x27;creates and retrieves user&#x27;, async () =&gt; {
const repo = dataSource.getRepository(User);
const user = await repo.save({ name: &#x27;Alice&#x27;, email: &#x27;[email protected]&#x27; });
const retrieved = await repo.findOneBy({ id: user.id });
expect(retrieved.name).toBe(&#x27;Alice&#x27;);
});
});</code></pre>
<p><strong>Strategy 3: Transaction Rollback</strong></p>
<pre><code class="lang-python"># Python (pytest)
@pytest.fixture
def db_session():
connection = engine.connect()
transaction = connection.begin()
Session = sessionmaker(bind=connection)
session = Session()
yield session
session.close()
transaction.rollback()
connection.close()
# Each test gets clean state via rollback
def test_create_user(db_session):
user = User(name=&quot;Alice&quot;)
db_session.add(user)
db_session.commit()
assert db_session.query(User).count() == 1</code></pre>
<pre><code class="lang-go">// Go
func TestUserRepository(t *testing.T) {
db := setupTestDB(t)
tx := db.Begin()
defer tx.Rollback()
repo := NewUserRepository(tx)
user, err := repo.Create(&quot;Alice&quot;, &quot;[email protected]&quot;)
require.NoError(t, err)
retrieved, err := repo.FindByID(user.ID)
require.NoError(t, err)
assert.Equal(t, &quot;Alice&quot;, retrieved.Name)
}</code></pre>
<h2>Patterns</h2>
<h3>API Integration Testing</h3>
<pre><code class="lang-python"># Python (FastAPI with TestClient)
from fastapi.testclient import TestClient
from myapp.main import app
client = TestClient(app)
def test_create_user_endpoint():
# Arrange
payload = {
&quot;name&quot;: &quot;Alice&quot;,
&quot;email&quot;: &quot;[email protected]&quot;
}
# Act
response = client.post(&quot;/users&quot;, json=payload)
# Assert
assert response.status_code == 201
data = response.json()
assert data[&quot;name&quot;] == &quot;Alice&quot;
assert &quot;id&quot; in data
def test_get_user_endpoint(db_session):
# Arrange: Create user in DB
user = User(name=&quot;Alice&quot;, email=&quot;[email protected]&quot;)
db_session.add(user)
db_session.commit()
# Act
response = client.get(f&quot;/users/{user.id}&quot;)
# Assert
assert response.status_code == 200
assert response.json()[&quot;name&quot;] == &quot;Alice&quot;
def test_authentication_required():
response = client.get(&quot;/protected-resource&quot;)
assert response.status_code == 401
response = client.get(
&quot;/protected-resource&quot;,
headers={&quot;Authorization&quot;: &quot;Bearer valid-token&quot;}
)
assert response.status_code == 200</code></pre>
<pre><code class="lang-typescript">// TypeScript (Express + Supertest)
import request from &#x27;supertest&#x27;;
import { app } from &#x27;./app&#x27;;
import { setupTestDB, teardownTestDB } from &#x27;./test-helpers&#x27;;
describe(&#x27;User API&#x27;, () =&gt; {
beforeAll(async () =&gt; {
await setupTestDB();
});
afterAll(async () =&gt; {
await teardownTestDB();
});
it(&#x27;creates user via POST /users&#x27;, async () =&gt; {
const response = await request(app)
.post(&#x27;/users&#x27;)
.send({ name: &#x27;Alice&#x27;, email: &#x27;[email protected]&#x27; })
.expect(201);
expect(response.body.name).toBe(&#x27;Alice&#x27;);
expect(response.body.id).toBeDefined();
});
it(&#x27;retrieves user via GET /users/:id&#x27;, async () =&gt; {
const createRes = await request(app)
.post(&#x27;/users&#x27;)
.send({ name: &#x27;Bob&#x27;, email: &#x27;[email protected]&#x27; });
const userId = createRes.body.id;
const response = await request(app)
.get(`/users/${userId}`)
.expect(200);
expect(response.body.name).toBe(&#x27;Bob&#x27;);
});
});</code></pre>
<h3>Testing Database Migrations</h3>
<pre><code class="lang-python"># Python (Alembic)
import pytest
from alembic import command
from alembic.config import Config
def test_migrations_run_successfully():
config = Config(&quot;alembic.ini&quot;)
config.set_main_option(&quot;sqlalchemy.url&quot;, &quot;sqlite:///:memory:&quot;)
# Run all migrations
command.upgrade(config, &quot;head&quot;)
# Verify schema exists
engine = create_engine(&quot;sqlite:///:memory:&quot;)
inspector = inspect(engine)
tables = inspector.get_table_names()
assert &quot;users&quot; in tables
assert &quot;posts&quot; in tables
def test_migration_rollback():
config = Config(&quot;alembic.ini&quot;)
config.set_main_option(&quot;sqlalchemy.url&quot;, &quot;sqlite:///:memory:&quot;)
# Upgrade to latest
command.upgrade(config, &quot;head&quot;)
# Downgrade one version
command.downgrade(config, &quot;-1&quot;)
# Verify rollback worked
# ... assertions ...</code></pre>
<h3>Testing with Redis/Cache</h3>
<pre><code class="lang-python"># Python (fakeredis)
import pytest
from fakeredis import FakeRedis
@pytest.fixture
def redis_client():
return FakeRedis()
def test_cache_set_get(redis_client):
cache = CacheService(redis_client)
cache.set(&quot;key&quot;, &quot;value&quot;, ttl=60)
assert cache.get(&quot;key&quot;) == &quot;value&quot;
def test_cache_expiration(redis_client):
cache = CacheService(redis_client)
cache.set(&quot;key&quot;, &quot;value&quot;, ttl=0)
time.sleep(0.1)
assert cache.get(&quot;key&quot;) is None</code></pre>
<pre><code class="lang-typescript">// TypeScript (ioredis-mock)
import RedisMock from &#x27;ioredis-mock&#x27;;
describe(&#x27;CacheService&#x27;, () =&gt; {
let redis: RedisMock;
let cache: CacheService;
beforeEach(() =&gt; {
redis = new RedisMock();
cache = new CacheService(redis);
});
it(&#x27;sets and gets values&#x27;, async () =&gt; {
await cache.set(&#x27;key&#x27;, &#x27;value&#x27;, 60);
const result = await cache.get(&#x27;key&#x27;);
expect(result).toBe(&#x27;value&#x27;);
});
});</code></pre>
<h3>Testing Message Queues</h3>
<pre><code class="lang-python"># Python (testing with in-memory queue)
import pytest
from queue import Queue
class InMemoryQueue:
def __init__(self):
self.queue = Queue()
def publish(self, message):
self.queue.put(message)
def consume(self, timeout=1):
return self.queue.get(timeout=timeout)
@pytest.fixture
def message_queue():
return InMemoryQueue()
def test_order_processing(message_queue):
# Arrange
order_service = OrderService(message_queue)
payment_processor = PaymentProcessor(message_queue)
# Act
order_service.create_order(user_id=1, items=[&quot;item1&quot;])
# Assert: Message published
message = message_queue.consume(timeout=1)
assert message[&quot;type&quot;] == &quot;order_created&quot;
assert message[&quot;user_id&quot;] == 1
# Act: Process payment
payment_processor.process(message)
# Assert: Payment message published
payment_message = message_queue.consume(timeout=1)
assert payment_message[&quot;type&quot;] == &quot;payment_processed&quot;</code></pre>
<h3>Testing External Service Integrations</h3>
<pre><code class="lang-python"># Python (using requests-mock)
import pytest
import requests_mock
def test_weather_api_integration():
with requests_mock.Mocker() as m:
# Mock external API
m.get(
&quot;https://api.weather.com/forecast&quot;,
json={&quot;temperature&quot;: 72, &quot;condition&quot;: &quot;sunny&quot;}
)
# Test service that calls API
service = WeatherService()
forecast = service.get_forecast(zip_code=&quot;94102&quot;)
assert forecast.temperature == 72
assert forecast.condition == &quot;sunny&quot;
def test_api_timeout_handling():
with requests_mock.Mocker() as m:
m.get(&quot;https://api.weather.com/forecast&quot;, exc=requests.Timeout)
service = WeatherService()
with pytest.raises(WeatherServiceError, match=&quot;timeout&quot;):
service.get_forecast(zip_code=&quot;94102&quot;)</code></pre>
<pre><code class="lang-typescript">// TypeScript (MSW - Mock Service Worker)
import { rest } from &#x27;msw&#x27;;
import { setupServer } from &#x27;msw/node&#x27;;
const server = setupServer(
rest.get(&#x27;https://api.weather.com/forecast&#x27;, (req, res, ctx) =&gt; {
return res(ctx.json({ temperature: 72, condition: &#x27;sunny&#x27; }));
})
);
beforeAll(() =&gt; server.listen());
afterEach(() =&gt; server.resetHandlers());
afterAll(() =&gt; server.close());
describe(&#x27;WeatherService&#x27;, () =&gt; {
it(&#x27;fetches forecast from API&#x27;, async () =&gt; {
const service = new WeatherService();
const forecast = await service.getForecast(&#x27;94102&#x27;);
expect(forecast.temperature).toBe(72);
expect(forecast.condition).toBe(&#x27;sunny&#x27;);
});
it(&#x27;handles API errors&#x27;, async () =&gt; {
server.use(
rest.get(&#x27;https://api.weather.com/forecast&#x27;, (req, res, ctx) =&gt; {
return res(ctx.status(500));
})
);
const service = new WeatherService();
await expect(service.getForecast(&#x27;94102&#x27;)).rejects.toThrow();
});
});</code></pre>
<h2>Examples by Language</h2>
<h3>Python (pytest + SQLAlchemy)</h3>
<pre><code class="lang-python"># conftest.py
import pytest
from sqlalchemy import create_engine
from sqlalchemy.orm import sessionmaker
from testcontainers.postgres import PostgresContainer
@pytest.fixture(scope=&quot;session&quot;)
def postgres():
with PostgresContainer(&quot;postgres:16&quot;) as container:
yield container
@pytest.fixture(scope=&quot;session&quot;)
def engine(postgres):
engine = create_engine(postgres.get_connection_url())
Base.metadata.create_all(engine)
return engine
@pytest.fixture
def db_session(engine):
connection = engine.connect()
transaction = connection.begin()
Session = sessionmaker(bind=connection)
session = Session()
yield session
session.close()
transaction.rollback()
connection.close()
# test_user_repository.py
def test_create_and_find_user(db_session):
repo = UserRepository(db_session)
user = repo.create(name=&quot;Alice&quot;, email=&quot;[email protected]&quot;)
assert user.id is not None
found = repo.find_by_email(&quot;[email protected]&quot;)
assert found.name == &quot;Alice&quot;
def test_user_unique_email_constraint(db_session):
repo = UserRepository(db_session)
repo.create(name=&quot;Alice&quot;, email=&quot;[email protected]&quot;)
with pytest.raises(IntegrityError):
repo.create(name=&quot;Bob&quot;, email=&quot;[email protected]&quot;)</code></pre>
<h3>Go (testcontainers-go)</h3>
<pre><code class="lang-go">// integration_test.go
package repository_test
import (
&quot;context&quot;
&quot;testing&quot;
&quot;github.com/stretchr/testify/assert&quot;
&quot;github.com/stretchr/testify/require&quot;
&quot;github.com/testcontainers/testcontainers-go&quot;
&quot;github.com/testcontainers/testcontainers-go/wait&quot;
)
func setupPostgres(t *testing.T) *sql.DB {
ctx := context.Background()
req := testcontainers.ContainerRequest{
Image: &quot;postgres:16&quot;,
ExposedPorts: []string{&quot;5432/tcp&quot;},
Env: map[string]string{
&quot;POSTGRES_PASSWORD&quot;: &quot;test&quot;,
&quot;POSTGRES_DB&quot;: &quot;testdb&quot;,
},
WaitingFor: wait.ForLog(&quot;database system is ready&quot;),
}
container, err := testcontainers.GenericContainer(ctx, testcontainers.GenericContainerRequest{
ContainerRequest: req,
Started: true,
})
require.NoError(t, err)
t.Cleanup(func() {
container.Terminate(ctx)
})
host, _ := container.Host(ctx)
port, _ := container.MappedPort(ctx, &quot;5432&quot;)
dsn := fmt.Sprintf(&quot;host=%s port=%s user=postgres password=test dbname=testdb sslmode=disable&quot;,
host, port.Port())
db, err := sql.Open(&quot;postgres&quot;, dsn)
require.NoError(t, err)
return db
}
func TestUserRepository(t *testing.T) {
db := setupPostgres(t)
defer db.Close()
repo := NewUserRepository(db)
user, err := repo.Create(&quot;Alice&quot;, &quot;[email protected]&quot;)
require.NoError(t, err)
assert.NotZero(t, user.ID)
found, err := repo.FindByEmail(&quot;[email protected]&quot;)
require.NoError(t, err)
assert.Equal(t, &quot;Alice&quot;, found.Name)
}</code></pre>
<h3>TypeScript (Vitest + TypeORM)</h3>
<pre><code class="lang-typescript">// test-setup.ts
import { DataSource } from &#x27;typeorm&#x27;;
import { PostgreSqlContainer } from &#x27;@testcontainers/postgresql&#x27;;
export async function setupTestDB(): Promise&lt;DataSource&gt; {
const container = await new PostgreSqlContainer(&#x27;postgres:16&#x27;).start();
const dataSource = new DataSource({
type: &#x27;postgres&#x27;,
host: container.getHost(),
port: container.getPort(),
username: container.getUsername(),
password: container.getPassword(),
database: container.getDatabase(),
entities: [User, Post],
synchronize: true,
});
await dataSource.initialize();
return dataSource;
}
// user-repository.test.ts
describe(&#x27;UserRepository&#x27;, () =&gt; {
let dataSource: DataSource;
let repository: Repository&lt;User&gt;;
beforeAll(async () =&gt; {
dataSource = await setupTestDB();
repository = dataSource.getRepository(User);
});
afterAll(async () =&gt; {
await dataSource.destroy();
});
afterEach(async () =&gt; {
await repository.clear();
});
it(&#x27;creates and retrieves user&#x27;, async () =&gt; {
const user = await repository.save({
name: &#x27;Alice&#x27;,
email: &#x27;[email protected]&#x27;
});
const found = await repository.findOneBy({ email: &#x27;[email protected]&#x27; });
expect(found?.name).toBe(&#x27;Alice&#x27;);
});
});</code></pre>
<h2>Checklist</h2>
<p><strong>Before Writing Integration Tests</strong>:</p>
<ul><li>[ ] Identify components to test together</li><li>[ ] Choose test database strategy (in-memory, containers, rollback)</li><li>[ ] Plan test data setup and teardown</li><li>[ ] Decide on test isolation level (per-test, per-suite)</li></ul>
<p><strong>Setting Up Infrastructure</strong>:</p>
<ul><li>[ ] Use test containers for real infrastructure</li><li>[ ] Configure test database with migrations</li><li>[ ] Set up test API server/client</li><li>[ ] Mock external services (or use contract tests)</li></ul>
<p><strong>Writing Tests</strong>:</p>
<ul><li>[ ] Clean state before each test (rollback or cleanup)</li><li>[ ] Test realistic workflows (multiple operations)</li><li>[ ] Verify data persistence across operations</li><li>[ ] Test error conditions and rollback scenarios</li><li>[ ] Keep tests independent (no order dependencies)</li></ul>
<p><strong>Performance</strong>:</p>
<ul><li>[ ] Tests complete in reasonable time (&lt; 5s each)</li><li>[ ] Use transactions for faster rollback</li><li>[ ] Share expensive resources (DB, containers) across tests</li><li>[ ] Parallelize when possible</li></ul>
<p><strong>After Writing Tests</strong>:</p>
<ul><li>[ ] Tests pass consistently (no flakiness)</li><li>[ ] Tests fail when integration breaks</li><li>[ ] Clean shutdown of resources (no port conflicts)</li><li>[ ] Tests run in CI/CD pipeline</li></ul>
<h2>Anti-Patterns</h2>
<pre><code>❌ NEVER: Share state between tests without cleanup
→ Flaky tests, order dependencies
❌ NEVER: Use production database for tests
→ Data corruption, slow tests
❌ NEVER: Skip transaction rollback in teardown
→ Polluted database state
❌ NEVER: Test too many layers at once
→ Slow, hard to debug failures
❌ NEVER: Ignore test performance
→ Slow feedback loop, developers skip tests
❌ NEVER: Mock everything in integration tests
→ Defeats purpose of integration testing
❌ NEVER: Leave containers running after tests
→ Resource leaks, port conflicts</code></pre>
<h2>Level 3: Resources</h2>
<h3>Comprehensive Reference</h3>
<p>See <code>/resources/REFERENCE.md</code> for in-depth coverage:</p>
<ul><li>Testing pyramid and integration test positioning (958 lines)</li><li>Test scopes and boundaries (narrow, medium, broad)</li><li>Test doubles (dummies, stubs, fakes, mocks, spies) with detailed examples</li><li>Contract testing with Pact and Spring Cloud Contract</li><li>Service virtualization with WireMock and MockServer</li><li>Database testing strategies (in-memory, Docker, transactions, migrations)</li><li>External service testing (HTTP APIs, GraphQL, message queues)</li><li>API integration testing patterns (REST, authentication, performance)</li><li>Message queue testing (RabbitMQ, Kafka, event-driven systems)</li><li>CI/CD integration patterns (GitHub Actions, GitLab CI, Docker Compose)</li><li>Performance and load testing (response times, Locust, concurrency)</li><li>Common anti-patterns and solutions (12 detailed patterns)</li><li>Best practices (10 comprehensive guidelines)</li></ul>
<h3>Executable Scripts</h3>
<p><strong><code>/resources/scripts/run_integration_tests.sh</code></strong> Orchestrates integration tests with automatic setup/teardown:</p>
<ul><li>Starts Docker services (PostgreSQL, Redis, RabbitMQ, etc.)</li><li>Waits for health checks</li><li>Runs tests with multiple frameworks (pytest, vitest, jest, go)</li><li>Generates reports with coverage</li><li>Cleans up infrastructure</li><li>Supports parallel execution, custom patterns, timeouts</li><li>Usage: <code>./run_integration_tests.sh --coverage --parallel</code></li></ul>
<p><strong><code>/resources/scripts/analyze_test_coverage.py</code></strong> Analyzes integration test coverage across multiple dimensions:</p>
<ul><li>Discovers test files and categorizes by type</li><li>Identifies tested vs untested components (endpoints, models, services, repositories)</li><li>Analyzes integration types (database, cache, queue, email, storage, API)</li><li>Generates actionable recommendations prioritized by impact</li><li>Outputs text or JSON reports</li><li>Usage: <code>./analyze_test_coverage.py --test-dir tests/integration --src-dir src</code></li></ul>
<p><strong><code>/resources/scripts/generate_test_report.py</code></strong> Generates comprehensive HTML/JSON reports from test results:</p>
<ul><li>Parses JUnit XML and pytest JSON formats</li><li>Includes test execution details, durations, failures</li><li>Visualizes coverage data with progress bars</li><li>Provides interactive HTML reports with test filtering</li><li>Outputs JSON for CI/CD pipeline integration</li><li>Usage: <code>./generate_test_report.py --input results.xml --coverage coverage.xml --output report.html</code></li></ul>
<h3>Runnable Examples</h3>
<p><strong>Python Examples</strong> (<code>/resources/examples/python/</code>):</p>
<ul><li><code>test_api_integration.py</code>: FastAPI testing with TestClient, PostgreSQL testcontainers, full CRUD lifecycle, authentication, performance tests (300+ lines)</li><li><code>test_database_integration.py</code>: Repository pattern testing, transactions, relationships, cascade deletes, constraint testing (400+ lines)</li></ul>
<p><strong>TypeScript Examples</strong> (<code>/resources/examples/typescript/</code>):</p>
<ul><li><code>test_api_integration.test.ts</code>: Express API testing with Supertest, PostgreSQL Pool, CRUD operations, pagination, performance tests (350+ lines)</li></ul>
<p><strong>Docker Infrastructure</strong> (<code>/resources/examples/docker/</code>):</p>
<ul><li><code>docker-compose-test.yml</code>: Complete test infrastructure with PostgreSQL, Redis, RabbitMQ, MongoDB, MySQL, MinIO, Elasticsearch, Mailhog, WireMock - all with health checks</li></ul>
<p>All scripts are production-ready with:</p>
<ul><li>Comprehensive --help documentation</li><li>JSON output support for CI/CD</li><li>Error handling and exit codes</li><li>Verbose logging options</li><li>Cross-platform compatibility</li></ul>
<h2>Related Skills</h2>
<p><strong>Foundation</strong>:</p>
<ul><li><code>unit-testing-patterns.md</code> - Testing individual components</li><li><code>test-driven-development.md</code> - TDD workflow</li></ul>
<p><strong>Database Testing</strong>:</p>
<ul><li><code>database-migrations.md</code> - Migration testing patterns</li><li><code>database-testing-patterns.md</code> - Advanced DB testing</li></ul>
<p><strong>API Testing</strong>:</p>
<ul><li><code>e2e-testing.md</code> - Full system testing</li><li><code>api-testing.md</code> - REST/GraphQL testing patterns</li></ul>
<p><strong>Infrastructure</strong>:</p>
<ul><li><code>test-containers.md</code> - Docker container testing</li><li><code>testing-microservices.md</code> - Service integration testing</li></ul>
<p><strong>Tools</strong>:</p>
<ul><li>Python: pytest, testcontainers, requests-mock</li><li>TypeScript: Vitest, Supertest, MSW, testcontainers</li><li>Go: testify, testcontainers-go</li><li>Rust: sqlx with test macros</li></ul>
<footer>
<div class="fmap">
<div><b>Build</b>
<a href="https://hanzo.app">hanzo.app</a> app builder
<a href="https://hanzo.codes">hanzo.codes</a> code with an agent
<a href="https://hanzoskills.com">hanzoskills.com</a> what an agent reads</div>
<div><b>Run</b>
<a href="https://console.hanzo.ai">console.hanzo.ai</a> cloud console
<a href="https://api.hanzo.ai">api.hanzo.ai</a> the API</div>
<div><b>Account</b>
<a href="https://hanzo.id">hanzo.id</a> sign in
<a href="https://pay.hanzo.ai">pay.hanzo.ai</a> top up
<a href="https://billing.hanzo.ai">billing.hanzo.ai</a> invoices and usage</div>
<div><b>Company</b>
<a href="https://hanzo.ai">hanzo.ai</a> canonical
<a href="https://hanzo.ventures">hanzo.ventures</a> ventures</div>
</div>
<div class="fend"><a href="/testing-integration-testing.md">This page as plain text</a> · <a href="/llms.txt">Index for agents</a></div>
</footer>
</div></body></html>