컴포넌트 테스트: 실제 브라우저 없이 사용자 행동을 어디까지 검증할 수 있는가

import { useState, type FormEvent } from 'react'
 
export type SaveName = (name: string) => Promise<void>
 
type Props = {
  initialName: string
  saveName: SaveName
}
 
export default function ProfileNameFormBad({ initialName, saveName }: Props) {
  const [name, setName] = useState(initialName)
  const [status, setStatus] = useState<'idle' | 'saving' | 'saved'>('idle')
 
  async function handleSubmit(event: FormEvent<HTMLFormElement>) {
    event.preventDefault()
    setStatus('saving')
    await saveName(name.trim())
    setStatus('saved')
  }
 
  return (
    <form onSubmit={handleSubmit}>
      <label htmlFor="profile-name">이름</label>
      <input
        id="profile-name"
        value={name}
        onChange={(event) => setName(event.target.value)}
      />
      <button type="button">저장</button>
      {status === 'saving' && <p>저장 중</p>}
      {status === 'saved' && <p>저장 완료</p>}
    </form>
  )
}

import { expect, test, vi } from 'vitest'
import type { SaveName } from './profile-name-form-bad'
 
test('새 이름을 저장할 수 있다', async () => {
  const saveName = vi.fn<SaveName>().mockResolvedValue(undefined)
 
  await saveName('새 이름')
 
  expect(saveName).toHaveBeenCalledWith('새 이름')
})

pnpm add -D @testing-library/[email protected] @testing-library/[email protected]
pnpm add -D @testing-library/[email protected] @testing-library/[email protected]
pnpm add -D [email protected] [email protected]

import { defineConfig } from 'vitest/config'
 
export default defineConfig({
  test: {
    environment: 'jsdom',
    setupFiles: ['./src/test/setup.ts'],
  },
})

import '@testing-library/jest-dom/vitest'
import { cleanup } from '@testing-library/react'
import { afterEach } from 'vitest'
 
afterEach(() => {
  cleanup()
})

import { render, screen } from '@testing-library/react'
import userEvent from '@testing-library/user-event'
import { expect, test, vi } from 'vitest'
import ProfileNameFormBad, { type SaveName } from './profile-name-form-bad'
 
test('사용자가 저장 버튼을 누르면 현재 이름을 저장한다', async () => {
  const user = userEvent.setup()
  const saveName = vi.fn<SaveName>().mockResolvedValue(undefined)
  render(<ProfileNameFormBad initialName="이전 이름" saveName={saveName} />)
 
  const nameInput = screen.getByRole('textbox', { name: '이름' })
  await user.clear(nameInput)
  await user.type(nameInput, '새 이름')
  await user.click(screen.getByRole('button', { name: '저장' }))
 
  expect(saveName).toHaveBeenCalledWith('새 이름')
})

pnpm exec vitest run src/profile-name-form.test.tsx

import { useState, type FormEvent } from 'react'
 
export type SaveName = (name: string) => Promise<void>
 
type Props = {
  initialName: string
  saveName: SaveName
}
 
type Status = 'idle' | 'saving' | 'saved' | 'error'
 
export default function ProfileNameForm({ initialName, saveName }: Props) {
  const [name, setName] = useState(initialName)
  const [status, setStatus] = useState<Status>('idle')
  const canSubmit = name.trim().length > 0 && status !== 'saving'
 
  async function handleSubmit(event: FormEvent<HTMLFormElement>) {
    event.preventDefault()
    if (!canSubmit) return
 
    setStatus('saving')
    try {
      await saveName(name.trim())
      setStatus('saved')
    } catch {
      setStatus('error')
    }
  }
 
  return (
    <form onSubmit={handleSubmit}>
      <label htmlFor="profile-name">이름</label>
      <input
        id="profile-name"
        value={name}
        disabled={status === 'saving'}
        onChange={(event) => {
          setName(event.target.value)
          setStatus('idle')
        }}
      />
      <button type="submit" disabled={!canSubmit}>
        {status === 'saving' ? '저장 중' : '저장'}
      </button>
      {status === 'saved' && <p>저장 완료</p>}
      {status === 'error' && <p>저장 실패: 다시 시도해 주세요.</p>}
    </form>
  )
}

import { render, screen } from '@testing-library/react'
import userEvent from '@testing-library/user-event'
import { expect, test, vi } from 'vitest'
import ProfileNameForm, { type SaveName } from './profile-name-form'
 
function createDeferred() {
  const controls: { resolve?: () => void } = {}
  const promise = new Promise<void>((resolve) => {
    controls.resolve = resolve
  })
 
  return {
    promise,
    resolve() {
      if (!controls.resolve) throw new Error('resolve가 준비되지 않았습니다.')
      controls.resolve()
    },
  }
}
 
test('저장 중 중복 제출을 막고 완료 상태로 전환한다', async () => {
  const user = userEvent.setup()
  const deferredSave = createDeferred()
  const saveName = vi.fn<SaveName>(() => deferredSave.promise)
  render(<ProfileNameForm initialName="이전 이름" saveName={saveName} />)
 
  const nameInput = screen.getByRole('textbox', { name: '이름' })
  await user.clear(nameInput)
  await user.type(nameInput, '새 이름')
 
  const saveButton = screen.getByRole('button', { name: '저장' })
  await user.click(saveButton)
 
  expect(saveName).toHaveBeenCalledOnce()
  expect(saveName).toHaveBeenCalledWith('새 이름')
  expect(nameInput).toBeDisabled()
  expect(saveButton).toBeDisabled()
  expect(saveButton).toHaveTextContent('저장 중')
 
  await user.click(saveButton)
  expect(saveName).toHaveBeenCalledOnce()
 
  deferredSave.resolve()
 
  expect(await screen.findByText('저장 완료')).toBeVisible()
  expect(nameInput).toBeEnabled()
  expect(screen.getByRole('button', { name: '저장' })).toBeEnabled()
})
 
test('저장 실패 뒤 입력값과 재시도 가능한 상태를 유지한다', async () => {
  const user = userEvent.setup()
  const saveName = vi.fn<SaveName>().mockRejectedValue(new Error('network'))
  render(<ProfileNameForm initialName="이전 이름" saveName={saveName} />)
 
  const nameInput = screen.getByRole('textbox', { name: '이름' })
  await user.clear(nameInput)
  await user.type(nameInput, '새 이름')
  await user.click(screen.getByRole('button', { name: '저장' }))
 
  expect(await screen.findByText('저장 실패: 다시 시도해 주세요.')).toBeVisible()
  expect(nameInput).toHaveValue('새 이름')
  expect(screen.getByRole('button', { name: '저장' })).toBeEnabled()
})

pnpm exec vitest run src/profile-name-form.test.tsx

문제       저장 함수 검사는 통과하지만 화면의 저장 버튼이 제출과 연결되지 않음
잘못된 판단 마지막 저장 함수를 직접 호출했으므로 사용자 경로도 검증됐다고 생각함
관찰       사용자 클릭 테스트에서 saveName 호출 기대가 실패함
원인       실제 React 컴포넌트, DOM과 이벤트 배선을 테스트 경계에서 제거함
행동       컴포넌트를 렌더하고 역할·이름으로 찾아 user-event로 조작함
검증       입력값, 호출 인자, 저장 중 비활성화, 완료·실패 문구를 각각 확인함