Integration Testing Pattern | Bootspring Docs

Test complete user flows and service interactions with database integration, API testing, and webhook verification.

Overview#

Integration tests verify that different parts of your application work together correctly. They test real database interactions, API endpoints, and service integrations to ensure the system functions as a whole.

When to use:

Testing complete user flows (registration, checkout)
Verifying database operations work correctly
Testing API endpoints with real data
Validating webhook handling

Key features:

Tests real database interactions
Verifies service integrations
Tests complete user journeys
Catches integration bugs

Code Example#

Database Integration Tests#

// __tests__/integration/setup.ts
import { PrismaClient } from '@prisma/client'
import { execSync } from 'child_process'

const prisma = new PrismaClient()

export async function setupTestDatabase() {
  // Reset database before tests
  await prisma.$executeRawUnsafe(`
    TRUNCATE TABLE "User", "Post", "Comment" CASCADE;
  `)
}

export async function teardownTestDatabase() {
  await prisma.$disconnect()
}

// Or use test containers
import { PostgreSqlContainer } from '@testcontainers/postgresql'

let container: PostgreSqlContainer

export async function startTestContainer() {
  container = await new PostgreSqlContainer()
    .withDatabase('testdb')
    .withUsername('test')
    .withPassword('test')
    .start()

  process.env.DATABASE_URL = container.getConnectionUri()

  // Run migrations
  execSync('npx prisma migrate deploy', {
    env: { ...process.env, DATABASE_URL: container.getConnectionUri() }
  })
}

export async function stopTestContainer() {
  await container?.stop()
}

User Flow Integration Test#

// __tests__/integration/user-flow.test.ts
import { prisma } from '@/lib/db'
import { POST as createUser } from '@/app/api/users/route'
import { POST as login } from '@/app/api/auth/login/route'
import { POST as createPost } from '@/app/api/posts/route'

describe('User Flow Integration', () => {
  beforeEach(async () => {
    await prisma.post.deleteMany()
    await prisma.user.deleteMany()
  })

  afterAll(async () => {
    await prisma.$disconnect()
  })

  it('completes full user registration and posting flow', async () => {
    // Step 1: Register user
    const registerRequest = new Request('http://localhost/api/users', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        email: 'test@example.com',
        password: 'password123',
        name: 'Test User'
      })
    })

    const registerResponse = await createUser(registerRequest)
    expect(registerResponse.status).toBe(201)

    const user = await registerResponse.json()
    expect(user.email).toBe('test@example.com')

    // Step 2: Login
    const loginRequest = new Request('http://localhost/api/auth/login', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        email: 'test@example.com',
        password: 'password123'
      })
    })

    const loginResponse = await login(loginRequest)
    expect(loginResponse.status).toBe(200)

    const { token } = await loginResponse.json()
    expect(token).toBeDefined()

    // Step 3: Create post
    const postRequest = new Request('http://localhost/api/posts', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        Authorization: `Bearer ${token}`
      },
      body: JSON.stringify({
        title: 'My First Post',
        content: 'Hello world!'
      })
    })

    const postResponse = await createPost(postRequest)
    expect(postResponse.status).toBe(201)

    const post = await postResponse.json()
    expect(post.title).toBe('My First Post')
    expect(post.authorId).toBe(user.id)

    // Verify in database
    const dbPost = await prisma.post.findUnique({
      where: { id: post.id },
      include: { author: true }
    })

    expect(dbPost?.author.email).toBe('test@example.com')
  })
})

API Integration Tests with Supertest#

// __tests__/integration/api.test.ts
import request from 'supertest'
import { createServer } from 'http'
import { parse } from 'url'
import next from 'next'

const dev = process.env.NODE_ENV !== 'production'
const app = next({ dev })
const handle = app.getRequestHandler()

let server: ReturnType<typeof createServer>

beforeAll(async () => {
  await app.prepare()
  server = createServer((req, res) => {
    const parsedUrl = parse(req.url!, true)
    handle(req, res, parsedUrl)
  })
  await new Promise<void>(resolve => server.listen(0, resolve))
})

afterAll(async () => {
  await new Promise<void>(resolve => server.close(() => resolve()))
  await app.close()
})

describe('API Integration Tests', () => {
  it('GET /api/health returns healthy status', async () => {
    const res = await request(server)
      .get('/api/health')
      .expect(200)

    expect(res.body.status).toBe('healthy')
  })

  it('POST /api/users creates a new user', async () => {
    const res = await request(server)
      .post('/api/users')
      .send({
        email: 'new@example.com',
        name: 'New User',
        password: 'password123'
      })
      .expect(201)

    expect(res.body.email).toBe('new@example.com')
    expect(res.body.password).toBeUndefined()
  })

  it('GET /api/users requires authentication', async () => {
    await request(server)
      .get('/api/users')
      .expect(401)
  })
})

Service Integration Tests#

// __tests__/integration/services.test.ts
import { PaymentService } from '@/services/payment'
import { EmailService } from '@/services/email'
import { prisma } from '@/lib/db'

// Mock external services
vi.mock('@/services/email', () => ({
  EmailService: {
    sendWelcomeEmail: vi.fn().mockResolvedValue(true),
    sendReceiptEmail: vi.fn().mockResolvedValue(true)
  }
}))

describe('Payment Service Integration', () => {
  beforeEach(async () => {
    await prisma.payment.deleteMany()
    await prisma.subscription.deleteMany()
    vi.clearAllMocks()
  })

  it('processes subscription and sends confirmation', async () => {
    const user = await prisma.user.create({
      data: {
        email: 'subscriber@example.com',
        name: 'Subscriber'
      }
    })

    // Process subscription
    const subscription = await PaymentService.createSubscription({
      userId: user.id,
      planId: 'pro',
      paymentMethodId: 'pm_test_123'
    })

    expect(subscription.status).toBe('active')
    expect(subscription.planId).toBe('pro')

    // Verify database state
    const dbSubscription = await prisma.subscription.findUnique({
      where: { id: subscription.id }
    })
    expect(dbSubscription?.userId).toBe(user.id)

    // Verify email was sent
    expect(EmailService.sendReceiptEmail).toHaveBeenCalledWith(
      expect.objectContaining({
        email: 'subscriber@example.com',
        subscriptionId: subscription.id
      })
    )
  })

  it('handles failed payment gracefully', async () => {
    const user = await prisma.user.create({
      data: {
        email: 'fail@example.com',
        name: 'Failed User'
      }
    })

    await expect(
      PaymentService.createSubscription({
        userId: user.id,
        planId: 'pro',
        paymentMethodId: 'pm_card_declined'
      })
    ).rejects.toThrow('Payment declined')

    // Verify no subscription was created
    const subscriptions = await prisma.subscription.findMany({
      where: { userId: user.id }
    })
    expect(subscriptions).toHaveLength(0)
  })
})

Webhook Integration Tests#

// __tests__/integration/webhooks.test.ts
import crypto from 'crypto'
import { POST } from '@/app/api/webhooks/stripe/route'
import { prisma } from '@/lib/db'

function createStripeSignature(payload: string, secret: string): string {
  const timestamp = Math.floor(Date.now() / 1000)
  const signedPayload = `${timestamp}.${payload}`
  const signature = crypto
    .createHmac('sha256', secret)
    .update(signedPayload)
    .digest('hex')

  return `t=${timestamp},v1=${signature}`
}

describe('Stripe Webhook Integration', () => {
  const webhookSecret = process.env.STRIPE_WEBHOOK_SECRET!

  beforeEach(async () => {
    await prisma.payment.deleteMany()
  })

  it('handles payment_intent.succeeded event', async () => {
    const user = await prisma.user.create({
      data: {
        email: 'payer@example.com',
        name: 'Payer',
        stripeCustomerId: 'cus_test_123'
      }
    })

    const event = {
      id: 'evt_test_123',
      type: 'payment_intent.succeeded',
      data: {
        object: {
          id: 'pi_test_123',
          amount: 2000,
          currency: 'usd',
          customer: 'cus_test_123',
          metadata: { userId: user.id }
        }
      }
    }

    const payload = JSON.stringify(event)
    const signature = createStripeSignature(payload, webhookSecret)

    const request = new Request('http://localhost/api/webhooks/stripe', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'stripe-signature': signature
      },
      body: payload
    })

    const response = await POST(request)
    expect(response.status).toBe(200)

    // Verify payment was recorded
    const payment = await prisma.payment.findFirst({
      where: { stripePaymentIntentId: 'pi_test_123' }
    })

    expect(payment).toBeDefined()
    expect(payment?.amount).toBe(2000)
    expect(payment?.status).toBe('succeeded')
  })

  it('rejects invalid signatures', async () => {
    const event = {
      id: 'evt_test_456',
      type: 'payment_intent.succeeded',
      data: { object: {} }
    }

    const request = new Request('http://localhost/api/webhooks/stripe', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'stripe-signature': 'invalid_signature'
      },
      body: JSON.stringify(event)
    })

    const response = await POST(request)
    expect(response.status).toBe(400)
  })
})

Database Transaction Tests#

// __tests__/integration/transactions.test.ts
import { prisma } from '@/lib/db'
import { transferFunds } from '@/services/banking'

describe('Database Transactions', () => {
  beforeEach(async () => {
    await prisma.account.deleteMany()
  })

  it('transfers funds atomically', async () => {
    const [sender, receiver] = await Promise.all([
      prisma.account.create({ data: { userId: 'user1', balance: 100 } }),
      prisma.account.create({ data: { userId: 'user2', balance: 0 } })
    ])

    await transferFunds(sender.id, receiver.id, 50)

    const [updatedSender, updatedReceiver] = await Promise.all([
      prisma.account.findUnique({ where: { id: sender.id } }),
      prisma.account.findUnique({ where: { id: receiver.id } })
    ])

    expect(updatedSender?.balance).toBe(50)
    expect(updatedReceiver?.balance).toBe(50)
  })

  it('rolls back on insufficient funds', async () => {
    const [sender, receiver] = await Promise.all([
      prisma.account.create({ data: { userId: 'user1', balance: 30 } }),
      prisma.account.create({ data: { userId: 'user2', balance: 0 } })
    ])

    await expect(transferFunds(sender.id, receiver.id, 50))
      .rejects.toThrow('Insufficient funds')

    // Verify no changes were made
    const [unchangedSender, unchangedReceiver] = await Promise.all([
      prisma.account.findUnique({ where: { id: sender.id } }),
      prisma.account.findUnique({ where: { id: receiver.id } })
    ])

    expect(unchangedSender?.balance).toBe(30)
    expect(unchangedReceiver?.balance).toBe(0)
  })
})

Usage Instructions#

Set up test database: Use separate database or test containers
Clean between tests: Reset database state in beforeEach
Test real interactions: Use actual database and API calls
Mock external services: Mock third-party APIs but test your integration code
Verify side effects: Check database state, emails sent, etc.

Best Practices#

Isolate tests - Each test should start with clean state
Use transactions - Wrap tests in transactions for easy rollback
Test happy and error paths - Verify both success and failure scenarios
Mock external services - Don't call real third-party APIs in tests
Use realistic data - Test with data similar to production
Test complete flows - Verify entire user journeys
Run in CI - Ensure integration tests run in your pipeline

Vitest - Test runner configuration
Fixtures - Test data management
Mocking - Mocking external services
E2E Testing - Full end-to-end testing