Hono Testing Patterns
Overview
Hono provides a simple testing approach: create a Request, pass it to your app, and validate the Response. The framework includes a typed test client for even better DX.
Key Features:
- Simple
app.request()API - Typed test client with full inference
- Environment mocking for Workers
- Works with Vitest, Jest, or any test runner
When to Use This Skill
Use Hono testing when:
- Writing unit tests for route handlers
- Integration testing API endpoints
- Testing middleware behavior
- Mocking Cloudflare Workers bindings
- Validating request/response cycles
Basic Testing
Using app.request()
import { Hono } from 'hono'
import { describe, it, expect } from 'vitest'
const app = new Hono()
app.get('/hello', (c) => c.text('Hello!'))
app.get('/json', (c) => c.json({ message: 'Hello' }))
describe('Basic routes', () => {
it('should return text', async () => {
const res = await app.request('/hello')
expect(res.status).toBe(200)
expect(await res.text()).toBe('Hello!')
})
it('should return JSON', async () => {
const res = await app.request('/json')
expect(res.status).toBe(200)
expect(res.headers.get('Content-Type')).toContain('application/json')
expect(await res.json()).toEqual({ message: 'Hello' })
})
})Request Options
// GET with query params
const res = await app.request('/search?q=hono&page=1')
// POST with JSON body
const res = await app.request('/users', {
method: 'POST',
headers: {
'Content-Type': 'application/json'
},
body: JSON.stringify({ name: 'Alice', email: 'alice@example.com' })
})
// POST with form data
const formData = new FormData()
formData.append('name', 'Alice')
formData.append('email', 'alice@example.com')
const res = await app.request('/users', {
method: 'POST',
body: formData
})
// With custom headers
const res = await app.request('/protected', {
headers: {
'Authorization': 'Bearer token123',
'X-Custom-Header': 'value'
}
})
// DELETE request
const res = await app.request('/users/123', {
method: 'DELETE'
})Typed Test Client
The test client provides full type inference:
import { Hono } from 'hono'
import { testClient } from 'hono/testing'
import { describe, it, expect } from 'vitest'
const app = new Hono()
.get('/users', (c) => c.json({ users: [] }))
.post('/users', async (c) => {
const body = await c.req.json()
return c.json({ id: '1', ...body }, 201)
})
.get('/users/:id', (c) => {
return c.json({ id: c.req.param('id'), name: 'Alice' })
})
describe('Users API', () => {
const client = testClient(app)
it('should list users', async () => {
const res = await client.users.$get()
expect(res.status).toBe(200)
const data = await res.json()
expect(data.users).toEqual([])
})
it('should create user', async () => {
const res = await client.users.$post({
json: { name: 'Alice', email: 'alice@example.com' }
})
expect(res.status).toBe(201)
const data = await res.json()
expect(data.name).toBe('Alice')
})
it('should get user by id', async () => {
const res = await client.users[':id'].$get({
param: { id: '123' }
})
expect(res.status).toBe(200)
const data = await res.json()
expect(data.id).toBe('123')
})
})Testing with Validation
import { Hono } from 'hono'
import { zValidator } from '@hono/zod-validator'
import { z } from 'zod'
const app = new Hono()
const createUserSchema = z.object({
name: z.string().min(1),
email: z.string().email()
})
app.post('/users', zValidator('json', createUserSchema), async (c) => {
const data = c.req.valid('json')
return c.json({ id: '1', ...data }, 201)
})
describe('Validation', () => {
it('should accept valid data', async () => {
const res = await app.request('/users', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
name: 'Alice',
email: 'alice@example.com'
})
})
expect(res.status).toBe(201)
})
it('should reject invalid email', async () => {
const res = await app.request('/users', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
name: 'Alice',
email: 'invalid-email'
})
})
expect(res.status).toBe(400)
})
it('should reject missing name', async () => {
const res = await app.request('/users', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
email: 'alice@example.com'
})
})
expect(res.status).toBe(400)
})
})Mocking Environment (Cloudflare Workers)
Mock Bindings
import { Hono } from 'hono'
type Bindings = {
DB: D1Database
KV: KVNamespace
API_KEY: string
}
const app = new Hono<{ Bindings: Bindings }>()
app.get('/data', async (c) => {
const result = await c.env.DB.prepare('SELECT * FROM users').all()
return c.json(result)
})
app.get('/config', (c) => {
return c.json({ apiKey: c.env.API_KEY.slice(0, 4) + '...' })
})
describe('With mocked bindings', () => {
// Mock D1 database
const mockDB = {
prepare: () => ({
all: async () => ({ results: [{ id: 1, name: 'Alice' }] }),
first: async () => ({ id: 1, name: 'Alice' }),
run: async () => ({ success: true })
})
}
// Mock KV namespace
const mockKV = {
get: async (key: string) => 'cached-value',
put: async (key: string, value: string) => {},
delete: async (key: string) => {}
}
const mockEnv: Bindings = {
DB: mockDB as unknown as D1Database,
KV: mockKV as unknown as KVNamespace,
API_KEY: 'test-api-key-12345' // pragma: allowlist secret
}
it('should use mocked database', async () => {
const res = await app.request('/data', {}, mockEnv)
expect(res.status).toBe(200)
const data = await res.json()
expect(data.results).toHaveLength(1)
})
it('should use mocked API key', async () => {
const res = await app.request('/config', {}, mockEnv)
const data = await res.json()
expect(data.apiKey).toBe('test...')
})
})Using Miniflare
For more realistic Cloudflare Workers testing:
import { Miniflare } from 'miniflare'
import { describe, it, expect, beforeAll, afterAll } from 'vitest'
describe('With Miniflare', () => {
let mf: Miniflare
beforeAll(async () => {
mf = new Miniflare({
script: `
import app from './src/index'
export default app
`,
modules: true,
d1Databases: ['DB'],
kvNamespaces: ['KV']
})
})
afterAll(async () => {
await mf.dispose()
})
it('should work with real bindings', async () => {
const res = await mf.dispatchFetch('http://localhost/data')
expect(res.status).toBe(200)
})
})Testing Middleware
import { Hono } from 'hono'
import { createMiddleware } from 'hono/factory'
// Middleware to test
const authMiddleware = createMiddleware(async (c, next) => {
const token = c.req.header('Authorization')?.replace('Bearer ', '')
if (!token) {
return c.json({ error: 'Unauthorized' }, 401)
}
if (token !== 'valid-token') {
return c.json({ error: 'Invalid token' }, 403)
}
c.set('userId', 'user-123')
await next()
})
const app = new Hono()
app.use('/protected/*', authMiddleware)
app.get('/protected/data', (c) => {
const userId = c.get('userId')
return c.json({ userId, data: 'secret' })
})
describe('Auth middleware', () => {
it('should reject request without token', async () => {
const res = await app.request('/protected/data')
expect(res.status).toBe(401)
expect(await res.json()).toEqual({ error: 'Unauthorized' })
})
it('should reject invalid token', async () => {
const res = await app.request('/protected/data', {
headers: { 'Authorization': 'Bearer invalid' }
})
expect(res.status).toBe(403)
expect(await res.json()).toEqual({ error: 'Invalid token' })
})
it('should allow valid token', async () => {
const res = await app.request('/protected/data', {
headers: { 'Authorization': 'Bearer valid-token' }
})
expect(res.status).toBe(200)
const data = await res.json()
expect(data.userId).toBe('user-123')
})
})Testing Error Handling
import { Hono } from 'hono'
import { HTTPException } from 'hono/http-exception'
const app = new Hono()
app.get('/error', () => {
throw new HTTPException(500, { message: 'Something went wrong' })
})
app.get('/not-found', (c) => {
return c.notFound()
})
app.onError((err, c) => {
if (err instanceof HTTPException) {
return c.json({ error: err.message }, err.status)
}
return c.json({ error: 'Internal error' }, 500)
})
app.notFound((c) => {
return c.json({ error: 'Not found' }, 404)
})
describe('Error handling', () => {
it('should handle HTTPException', async () => {
const res = await app.request('/error')
expect(res.status).toBe(500)
expect(await res.json()).toEqual({ error: 'Something went wrong' })
})
it('should handle not found', async () => {
const res = await app.request('/unknown-route')
expect(res.status).toBe(404)
expect(await res.json()).toEqual({ error: 'Not found' })
})
})Testing File Uploads
import { Hono } from 'hono'
const app = new Hono()
app.post('/upload', async (c) => {
const formData = await c.req.formData()
const file = formData.get('file') as File
if (!file) {
return c.json({ error: 'No file provided' }, 400)
}
return c.json({
filename: file.name,
size: file.size,
type: file.type
})
})
describe('File upload', () => {
it('should handle file upload', async () => {
const file = new File(['hello world'], 'test.txt', { type: 'text/plain' })
const formData = new FormData()
formData.append('file', file)
const res = await app.request('/upload', {
method: 'POST',
body: formData
})
expect(res.status).toBe(200)
const data = await res.json()
expect(data.filename).toBe('test.txt')
expect(data.size).toBe(11)
expect(data.type).toBe('text/plain')
})
it('should reject missing file', async () => {
const formData = new FormData()
const res = await app.request('/upload', {
method: 'POST',
body: formData
})
expect(res.status).toBe(400)
})
})Test Setup Patterns
Vitest Configuration
// vitest.config.ts
import { defineConfig } from 'vitest/config'
export default defineConfig({
test: {
globals: true,
environment: 'node',
coverage: {
reporter: ['text', 'json', 'html'],
exclude: ['node_modules/', 'dist/']
}
}
})Test Utilities
// test/utils.ts
import { Hono } from 'hono'
import type { Bindings } from '../src/types'
export function createTestApp() {
// Return fresh app instance for each test
return new Hono<{ Bindings: Bindings }>()
}
export function createMockEnv(overrides: Partial<Bindings> = {}): Bindings {
return {
DB: createMockDB(),
KV: createMockKV(),
API_KEY: 'test-key', // pragma: allowlist secret
...overrides
}
}
export function createMockDB() {
return {
prepare: (sql: string) => ({
bind: (...args: any[]) => ({
all: async () => ({ results: [] }),
first: async () => null,
run: async () => ({ success: true })
}),
all: async () => ({ results: [] }),
first: async () => null,
run: async () => ({ success: true })
})
}
}
export function createMockKV() {
const store = new Map<string, string>()
return {
get: async (key: string) => store.get(key) ?? null,
put: async (key: string, value: string) => { store.set(key, value) },
delete: async (key: string) => { store.delete(key) }
}
}Using Test Utilities
import { describe, it, expect, beforeEach } from 'vitest'
import { createTestApp, createMockEnv } from './utils'
import { setupRoutes } from '../src/routes'
describe('API Tests', () => {
let app: ReturnType<typeof createTestApp>
let env: ReturnType<typeof createMockEnv>
beforeEach(() => {
app = createTestApp()
env = createMockEnv()
setupRoutes(app)
})
it('should work with fresh instances', async () => {
const res = await app.request('/api/health', {}, env)
expect(res.status).toBe(200)
})
})Quick Reference
app.request() Signature
app.request(
path: string,
options?: RequestInit,
env?: Bindings
): Promise<Response>Common Assertions
// Status
expect(res.status).toBe(200)
expect(res.ok).toBe(true)
// Headers
expect(res.headers.get('Content-Type')).toContain('application/json')
expect(res.headers.get('X-Custom')).toBe('value')
// Body
expect(await res.text()).toBe('Hello')
expect(await res.json()).toEqual({ key: 'value' })
// Response properties
expect(res.redirected).toBe(false)
expect(res.url).toBe('http://localhost/path')Test Client Methods
const client = testClient(app)
client.path.$get()
client.path.$post({ json: {} })
client.path[':id'].$get({ param: { id: '1' } })
client.path.$get({ query: { page: 1 } })
client.path.$post({ header: { 'X-Custom': 'v' } })Related Skills
- hono-core - Framework fundamentals
- hono-middleware - Middleware patterns
- hono-validation - Request validation
Version: Hono 4.x Last Updated: January 2025 License: MIT