编辑“︁Next.js React Testing Library”︁（章节）

= Next.js React Testing Library =

== 介绍 ==
'''Next.js React Testing Library''' 是一个基于 [[React Testing Library]] 的测试工具集，专门用于测试 [[Next.js]] 应用程序中的组件和页面。它提供了一套简单、直观的 API，帮助开发者编写可维护、可读性强的测试代码，同时鼓励最佳实践，如避免测试实现细节，而是专注于用户行为。

React Testing Library 的核心思想是：
* 测试组件的行为，而非内部实现。
* 模拟用户交互（点击、输入等）。
* 提供查询方法（如 `getByText`、`getByRole`）来定位 DOM 元素。
* 支持异步操作（如 `waitFor`、`findBy`）。

在 Next.js 中，由于框架的特殊性（如路由、数据获取等），React Testing Library 需要结合 [[Jest]] 或其他测试运行器使用，并可能需要额外的配置。

== 安装与配置 ==
首先，确保你的 Next.js 项目已安装必要的依赖：

<syntaxhighlight lang="bash">
npm install --save-dev @testing-library/react @testing-library/jest-dom @testing-library/user-event jest @types/jest
</syntaxhighlight>

然后，在项目根目录创建或修改 `jest.config.js`：

<syntaxhighlight lang="javascript">
module.exports = {
  testEnvironment: 'jsdom',
  setupFilesAfterEnv: ['<rootDir>/jest.setup.js'],
};
</syntaxhighlight>

创建 `jest.setup.js` 文件以引入 `@testing-library/jest-dom` 的扩展断言：

<syntaxhighlight lang="javascript">
import '@testing-library/jest-dom/extend-expect';
</syntaxhighlight>

== 基本用法 ==
以下是一个简单的测试示例，测试一个 Next.js 页面组件：

=== 示例组件 ===
假设有一个 `Home` 组件 (`pages/index.js`)：

<syntaxhighlight lang="javascript">
export default function Home() {
  return (
    <div>
      <h1>Welcome to Next.js</h1>
      <button onClick={() => alert('Button clicked!')}>Click Me</button>
    </div>
  );
}
</syntaxhighlight>

=== 测试文件 ===
创建 `__tests__/index.test.js`：

<syntaxhighlight lang="javascript">
import { render, screen, fireEvent } from '@testing-library/react';
import Home from '../pages/index';

describe('Home Page', () => {
  it('renders a heading', () => {
    render(<Home />);
    const heading = screen.getByRole('heading', { name: /Welcome to Next.js/i });
    expect(heading).toBeInTheDocument();
  });

  it('shows alert when button is clicked', () => {
    window.alert = jest.fn();
    render(<Home />);
    const button = screen.getByRole('button', { name: /Click Me/i });
    fireEvent.click(button);
    expect(window.alert).toHaveBeenCalledWith('Button clicked!');
  });
});
</syntaxhighlight>

=== 解释 ===
1. `render` 函数渲染组件。
2. `screen.getByRole` 查询 DOM 元素（`heading` 和 `button`）。
3. `fireEvent.click` 模拟用户点击。
4. `expect` 断言验证结果。

== 高级用法 ==
=== 测试异步操作 ===
Next.js 中常见的数据获取（如 `getServerSideProps`）可以通过模拟 API 测试：

<syntaxhighlight lang="javascript">
import { render, screen, waitFor } from '@testing-library/react';
import Home from '../pages/index';

jest.mock('../lib/api', () => ({
  fetchData: jest.fn(() => Promise.resolve({ data: 'Mock Data' })),
}));

describe('Home Page with Data', () => {
  it('displays fetched data', async () => {
    render(<Home data={{ message: 'Hello' }} />);
    await waitFor(() => {
      expect(screen.getByText('Hello')).toBeInTheDocument();
    });
  });
});
</syntaxhighlight>

=== 测试路由 ===
使用 `next-router-mock` 测试路由行为：

<syntaxhighlight lang="bash">
npm install --save-dev next-router-mock
</syntaxhighlight>

测试示例：

<syntaxhighlight lang="javascript">
import { render, screen } from '@testing-library/react';
import Home from '../pages/index';
import mockRouter from 'next-router-mock';

jest.mock('next/router', () => require('next-router-mock'));

describe('Routing', () => {
  it('navigates on button click', () => {
    mockRouter.push('/initial-route');
    render(<Home />);
    fireEvent.click(screen.getByText('Navigate'));
    expect(mockRouter.pathname).toBe('/new-route');
  });
});
</syntaxhighlight>

== 实际案例 ==
=== 测试登录表单 ===
假设有一个登录组件：

<syntaxhighlight lang="javascript">
function LoginForm({ onSubmit }) {
  const [email, setEmail] = useState('');
  return (
    <form onSubmit={(e) => { e.preventDefault(); onSubmit(email); }}>
      <input 
        type="email" 
        value={email} 
        onChange={(e) => setEmail(e.target.value)} 
        placeholder="Email" 
      />
      <button type="submit">Login</button>
    </form>
  );
}
</syntaxhighlight>

测试文件：

<syntaxhighlight lang="javascript">
import { render, screen, fireEvent } from '@testing-library/react';
import LoginForm from '../components/LoginForm';

describe('LoginForm', () => {
  it('submits email', () => {
    const mockSubmit = jest.fn();
    render(<LoginForm onSubmit={mockSubmit} />);
    
    fireEvent.change(
      screen.getByPlaceholderText('Email'),
      { target: { value: 'test@example.com' } }
    );
    fireEvent.click(screen.getByText('Login'));
    
    expect(mockSubmit).toHaveBeenCalledWith('test@example.com');
  });
});
</syntaxhighlight>

== 最佳实践 ==
* 使用 `getByRole` 优先于其他查询方法。
* 避免使用 `container.querySelector` 直接访问 DOM。
* 对异步操作使用 `await waitFor` 或 `findBy*`。
* 模拟外部依赖（如 API、路由）。

== 常见问题 ==
{| class="wikitable"
|-
! 问题 !! 解决方案
|-
| 测试失败并显示 "Not wrapped in act(...)" | 使用 `await` 或 `waitFor` 处理异步更新
|-
| 路由测试不工作 | 确保正确模拟 `next/router`
|-
| 样式或 CSS 模块错误 | 在 Jest 配置中添加 `identity-obj-proxy`
|}

== 总结 ==
Next.js React Testing Library 是测试 Next.js 应用的强大工具，它强调以用户为中心的方式验证组件行为。通过结合 Jest 和适当的模拟，可以覆盖从简单渲染测试到复杂异步场景的全方位测试需求。

[[Category:后端框架]]
[[Category:Next.js]]
[[Category:Next.js测试]]