Purpose

Quick validation without ceremony. Write script, run against real deps, verify behavior, delete or document.

Characteristics

• Gitignored — never committed, purely local
• Disposable — delete after validation or promote to permanent tests
• Self-contained — runnable with single command
• Real dependencies — actual DB, real APIs, live services

Naming Conventions

• test-{feature}.ts — feature validation (test-auth-flow.ts)
• debug-{issue}.ts — investigate specific bug (debug-token-expiry.ts)
• prove-{behavior}.ts — demonstrate expected behavior (prove-rate-limiting.ts)
• explore-{api}.ts — learn external API behavior (explore-stripe-webhooks.ts)

Example Structure

// .scratch/test-auth-flow.ts
import { db } from '../src/db'
import { api } from '../src/api'

async function testAuthFlow() {
  // Setup: real test user in real database
  const user = await db.users.create({
    email: 'test@example.com',
    password: 'hashed-test-password'
  })

  // Execute: real HTTP requests
  const loginRes = await api.post('/auth/login', {
    email: user.email,
    password: 'test-password'
  })

  // Verify: actual response
  console.assert(loginRes.status === 200, 'Login should succeed')
  console.assert(loginRes.body.token, 'Should receive JWT token')

  const meRes = await api.get('/auth/me', {
    headers: { Authorization: `Bearer ${loginRes.body.token}` }
  })

  console.assert(meRes.status === 200, 'Auth should work')
  console.assert(meRes.body.email === user.email, 'Should return correct user')

  // Cleanup
  await db.users.delete({ id: user.id })

  console.log('✓ Auth flow validated')
}

testAuthFlow().catch(console.error)