epic-testing

name	epic-testing
description	Guide on testing with Vitest and Playwright for Epic Stack
categories	["testing","vitest","playwright","e2e"]

Epic Stack: Testing

When to use this skill

Use this skill when you need to:

• Write unit tests for utilities and components
• Create E2E tests with Playwright
• Test forms and validation
• Test routes and loaders
• Mock external services with MSW
• Test authentication and permissions
• Configure test database

Patterns and conventions

Testing Philosophy

Following Epic Web principles:

Tests should resemble users - Write tests that mirror how real users interact with your application. Test user workflows, not implementation details. If a user would click a button, your test should click that button. If a user would see an error message, your test should check for that specific message.

Make assertions specific - Be explicit about what you're testing. Instead of vague assertions, use specific, meaningful checks that clearly communicate the expected behavior. This makes tests easier to understand and debug when they fail.

Example - Tests that resemble users:

// ✅ Good - Tests user workflow
test('User can sign up and create their first note', async ({ page, navigate }) => {
	// User visits signup page
	await navigate('/signup')

	// User fills out form like a real person would
	await page.getByRole('textbox', { name: /email/i }).fill('[e-mail]')
	await page.getByRole('textbox', { name: /username/i }).fill('newuser')
	await page.getByRole('textbox', { name: /^password$/i }).fill('securepassword123')
	await page.getByRole('textbox', { name: /confirm/i }).fill('securepassword123')

	// User submits form
	await page.getByRole('button', { name: /sign up/i }).click()

	// User is redirected to onboarding
	await expect(page).toHaveURL(/\/onboarding/)

	// User creates their first note
	await navigate('/notes/new')
	await page.getByRole('textbox', { name: /title/i }).fill('My First Note')
	await page.getByRole('textbox', { name: /content/i }).fill('This is my first note!')
	await page.getByRole('button', { name: /create/i }).click()

	// User sees their note
	await expect(page.getByRole('heading', { name: 'My First Note' })).toBeVisible()
	await expect(page.getByText('This is my first note!')).toBeVisible()
})

// ❌ Avoid - Testing implementation details
test('Signup form calls API endpoint', async ({ page }) => {
	// This tests implementation, not user experience
	const response = await page.request.post('/signup', { data: {...} })
	expect(response.status()).toBe(200)
})

Example - Specific assertions:

// ✅ Good - Specific assertions
test('Form shows specific validation errors', async ({ page, navigate }) => {
	await navigate('/signup')
	await page.getByRole('button', { name: /sign up/i }).click()

	// Specific error messages that users would see
	await expect(page.getByText(/email is required/i)).toBeVisible()
	await expect(
		page.getByText(/username must be at least 3 characters/i),
	).toBeVisible()
	await expect(
		page.getByText(/password must be at least 6 characters/i),
	).toBeVisible()
})

// ❌ Avoid - Vague assertions
test('Form shows errors', async ({ page, navigate }) => {
	await navigate('/signup')
	await page.getByRole('button', { name: /sign up/i }).click()

	// Too vague - what errors? where?
	expect(page.locator('.error')).toBeVisible()
})

Two Types of Tests

Epic Stack uses two types of tests:

1. Unit Tests with Vitest - Tests for individual components and utilities
2. E2E Tests with Playwright - End-to-end tests of the complete flow

Unit Tests with Vitest

Basic setup:

// app/utils/my-util.test.ts
import { describe, expect, it } from 'vitest'
import { myUtil } from './my-util.ts'

describe('myUtil', () => {
	it('should do something', () => {
		expect(myUtil('input')).toBe('expected')
	})
})

Testing con DOM:

import { describe, expect, it } from 'vitest'
import { render, screen } from '@testing-library/react'
import { MyComponent } from './my-component.tsx'

describe('MyComponent', () => {
	it('should render correctly', () => {
		render(<MyComponent />)
		expect(screen.getByText('Hello')).toBeInTheDocument()
	})
})

E2E Tests with Playwright

Basic setup:

// tests/e2e/my-feature.test.ts
import { expect, test } from '#tests/playwright-utils.ts'

test('Users can do something', async ({ page, navigate, login }) => {
	const user = await login()
	await navigate('/my-page')

	// Interact with the page
	await page.getByRole('button', { name: /Submit/i }).click()

	// Verificar resultado
	await expect(page).toHaveURL('/success')
})

Login Fixture

Epic Stack provides a login fixture for authenticated tests.

Use login fixture:

test('Protected route', async ({ page, navigate, login }) => {
	const user = await login() // Creates user and session automatically
	await navigate('/protected')

	// User is authenticated
	await expect(page.getByText(`Welcome ${user.username}`)).toBeVisible()
})

Login with options:

const user = await login({
	username: 'testuser',
	email: '[e-mail]',
	password: 'password123',
})

Note: The user is automatically deleted when the test completes.

Insert User without Login

To create user without authentication:

test('Public content', async ({ page, navigate, insertNewUser }) => {
	const user = await insertNewUser({
		username: 'publicuser',
		email: '[e-mail]',
	})

	await navigate(`/users/${user.username}`)
	await expect(page.getByText(user.username)).toBeVisible()
})

Navigate Helper

Use the navigate helper to navigate with type-safety:

// Type-safe navigation
await navigate('/users/:username/notes', { username: user.username })
await navigate('/users/:username/notes/:noteId', {
	username: user.username,
	noteId: note.id,
})

// Also works with routes without parameters
await navigate('/login')

Test Database

Epic Stack uses a separate test database.

Automatic configuration:

• The test database is configured automatically
• It's cleaned between tests
• Data created in tests is automatically deleted

Create data in tests:

import { prisma } from '#app/utils/db.server.ts'

test('User can see notes', async ({ page, navigate, login }) => {
	const user = await login()

	// Create note in database
	const note = await prisma.note.create({
		data: {
			title: 'Test Note',
			content: 'Test Content',
			ownerId: user.id,
		},
	})

	await navigate('/users/:username/notes/:noteId', {
		username: user.username,
		noteId: note.id,
	})

	await expect(page.getByText('Test Note')).toBeVisible()
})

MSW (Mock Service Worker)

Epic Stack uses MSW to mock external services.

Mock example:

// tests/mocks/github.ts
import { http, HttpResponse } from 'msw'

export const handlers = [
	http.get('https://api.github.com/user', () => {
		return HttpResponse.json({
			id: '123',
			login: 'testuser',
			email: '[e-mail]',
		})
	}),
]

Use in tests: Mocks are automatically applied when MOCKS=true is configured.

Testing Forms

Test form:

test('User can submit form', async ({ page, navigate, login }) => {
	const user = await login()
	await navigate('/notes/new')

	// Fill form
	await page.getByRole('textbox', { name: /title/i }).fill('New Note')
	await page.getByRole('textbox', { name: /content/i }).fill('Note content')

	// Submit
	await page.getByRole('button', { name: /submit/i }).click()

	// Verificar redirect
	await expect(page).toHaveURL(new RegExp('/users/.*/notes/.*'))
})

Test validation:

test('Form shows validation errors', async ({ page, navigate }) => {
	await navigate('/signup')

	// Submit sin llenar
	await page.getByRole('button', { name: /submit/i }).click()

	// Verificar errores
	await expect(page.getByText(/email is required/i)).toBeVisible()
})

Testing Loaders

Test loader:

// app/utils/my-util.test.ts
import { describe, expect, it } from 'vitest'
import { loader } from '../routes/my-route.ts'
import { prisma } from '../utils/db.server.ts'

describe('loader', () => {
	it('should load data', async () => {
		// Create data
		const user = await prisma.user.create({
			data: {
				email: '[e-mail]',
				username: 'testuser',
				roles: { connect: { name: 'user' } },
			},
		})

		// Mock request
		const request = new Request('http://localhost/my-route')

		// Execute loader
		const result = await loader({ request, params: {}, context: {} })

		// Verify result
		expect(result.data).toBeDefined()
	})
})

Testing Actions

Test action:

// tests/e2e/notes.test.ts
test('User can create note', async ({ page, navigate, login }) => {
	const user = await login()
	await navigate('/users/:username/notes', { username: user.username })

	await page.getByRole('link', { name: /new note/i }).click()

	const formData = new FormData()
	formData.set('title', 'Test Note')
	formData.set('content', 'Test Content')

	await page.getByRole('textbox', { name: /title/i }).fill('Test Note')
	await page.getByRole('textbox', { name: /content/i }).fill('Test Content')
	await page.getByRole('button', { name: /submit/i }).click()

	// Verify that note was created
	await expect(page.getByText('Test Note')).toBeVisible()
})

Testing Permissions

Test permissions:

test('Only owner can delete note', async ({
	page,
	navigate,
	login,
	insertNewUser,
}) => {
	const owner = await login()
	const otherUser = await insertNewUser()

	const note = await prisma.note.create({
		data: {
			title: 'Test Note',
			content: 'Test',
			ownerId: owner.id,
		},
	})

	// Login as other user
	const session = await createSession(otherUser.id)
	await page.context().addCookies([getCookie(session)])

	await navigate('/users/:username/notes/:noteId', {
		username: owner.username,
		noteId: note.id,
	})

	// Verify that can't delete
	await expect(page.getByRole('button', { name: /delete/i })).not.toBeVisible()
})

DB Helpers

Create user:

import { createUser } from '#tests/db-utils.ts'

const userData = createUser() // Generates unique random data

Create password:

import { createPassword } from '#tests/db-utils.ts'

const password = createPassword('mypassword') // { hash: '...' }

Wait For Helper

To wait for async conditions:

import { waitFor } from '#tests/playwright-utils.ts'

await waitFor(
	async () => {
		const element = await page.getByText('Content loaded').first()
		expect(element).toBeVisible()
		return element
	},
	{ timeout: 5000, errorMessage: 'Content never loaded' },
)

Testing GitHub OAuth

Prepare GitHub user:

test('User can login with GitHub', async ({
	page,
	navigate,
	prepareGitHubUser,
}) => {
	const ghUser = await prepareGitHubUser()

	await navigate('/login')
	await page.getByRole('link', { name: /github/i }).click()

	// GitHub user is automatically prepared
	await expect(page).toHaveURL('/onboarding/github')
})

Common examples

Example 1: Complete E2E test (resembling user workflow)

// tests/e2e/notes.test.ts
import { expect, test } from '#tests/playwright-utils.ts'
import { prisma } from '#app/utils/db.server.ts'
import { faker } from '@faker-js/faker'

test('Users can create, edit, and delete notes', async ({
	page,
	navigate,
	login,
}) => {
	// User logs in (realistic workflow)
	const user = await login()
	await navigate('/users/:username/notes', { username: user.username })

	// User creates a new note (clicking link, filling form, submitting)
	await page.getByRole('link', { name: /new note/i }).click()
	const newNote = {
		title: faker.lorem.words(3),
		content: faker.lorem.paragraphs(2),
	}
	await page.getByRole('textbox', { name: /title/i }).fill(newNote.title)
	await page.getByRole('textbox', { name: /content/i }).fill(newNote.content)
	await page.getByRole('button', { name: /submit/i }).click()

	// Specific assertions: user sees their note with correct title and content
	await expect(page.getByRole('heading', { name: newNote.title })).toBeVisible()
	await expect(page.getByText(newNote.content)).toBeVisible()
	const noteUrl = page.url()
	const noteId = noteUrl.split('/').pop()

	// User edits the note (clicking edit, updating fields, saving)
	await page.getByRole('link', { name: /edit/i }).click()
	const updatedNote = {
		title: faker.lorem.words(3),
		content: faker.lorem.paragraphs(2),
	}
	await page.getByRole('textbox', { name: /title/i }).fill(updatedNote.title)
	await page
		.getByRole('textbox', { name: /content/i })
		.fill(updatedNote.content)
	await page.getByRole('button', { name: /submit/i }).click()

	// Specific assertions: user sees updated content
	await expect(
		page.getByRole('heading', { name: updatedNote.title }),
	).toBeVisible()
	await expect(page.getByText(updatedNote.content)).toBeVisible()

	// User deletes the note (clicking delete button)
	await page.getByRole('button', { name: /delete/i }).click()

	// Specific assertion: user is redirected back to notes list
	await expect(page).toHaveURL(`/users/${user.username}/notes`)
	await expect(page.getByText(updatedNote.title)).not.toBeVisible()
})

Example 2: Unit test for utility

// app/utils/misc.test.ts
import { describe, expect, it } from 'vitest'
import { cn } from './misc.tsx'

describe('cn', () => {
	it('should merge class names', () => {
		expect(cn('foo', 'bar')).toBe('foo bar')
		expect(cn('foo', undefined, 'bar')).toBe('foo bar')
		expect(cn('foo', false && 'bar', 'baz')).toBe('foo baz')
	})
})

Example 3: Form validation test

// tests/e2e/signup.test.ts
test('Signup form validation', async ({ page, navigate }) => {
	await navigate('/signup')

	// Submit without filling
	await page.getByRole('button', { name: /submit/i }).click()

	// Verify errors
	await expect(page.getByText(/email is required/i)).toBeVisible()

	// Fill invalid email
	await page.getByRole('textbox', { name: /email/i }).fill('invalid')
	await page.getByRole('button', { name: /submit/i }).click()

	// Verify email error
	await expect(page.getByText(/email is invalid/i)).toBeVisible()

	// Fill valid email
	await page.getByRole('textbox', { name: /email/i }).fill('[e-mail]')
	await page.getByRole('button', { name: /submit/i }).click()

	// Verify redirect to onboarding
	await expect(page).toHaveURL(/\/onboarding/)
})

Example 4: Permissions test

// tests/e2e/permissions.test.ts
test('Only admin can access admin routes', async ({
	page,
	navigate,
	login,
	insertNewUser,
}) => {
	// Test with normal user
	const normalUser = await login()

	await navigate('/admin/users')

	// Should redirect or show error
	await expect(page).toHaveURL('/') // Or verify error message

	// Test with admin
	await page.context().clearCookies()
	const admin = await insertNewUser()
	await prisma.user.update({
		where: { id: admin.id },
		data: {
			roles: {
				connect: { name: 'admin' },
			},
		},
	})

	// Login as admin
	const adminSession = await createSession(admin.id)
	await page.context().addCookies([getCookie(adminSession)])

	await navigate('/admin/users')

	// Now should work
	await expect(page.getByText('All Users')).toBeVisible()
})

Common mistakes to avoid

• ❌ Testing implementation details instead of user workflows: Write tests that mirror how users actually use your app
• ❌ Vague assertions: Use specific, meaningful assertions that clearly communicate expected behavior
• ❌ Not cleaning data after tests: Epic Stack cleans automatically, but make sure not to depend on data between tests
• ❌ Assuming execution order: Tests must be independent
• ❌ Not using fixtures: Use login, insertNewUser, etc. instead of creating everything manually
• ❌ Hardcoding data: Use faker to generate unique data
• ❌ Not waiting for elements: Use expect with toBeVisible() instead of assuming it exists
• ❌ Not using type-safe navigation: Use navigate helper instead of page.goto() directly
• ❌ Forgetting MSW in tests: External services are automatically mocked when MOCKS=true
• ❌ Not testing error cases: Test both happy path and errors
• ❌ Testing internal state instead of user-visible behavior: Focus on what users see and do

References

• Epic Stack Testing Docs
• Epic Web Principles
• Vitest Documentation
• Playwright Documentation
• Testing Library
• MSW
• tests/playwright-utils.ts - Playwright fixtures and helpers
• tests/db-utils.ts - DB helpers for tests
• tests/e2e/ - E2E test examples
• app/utils/*.test.ts - Unit test examples