react-dnd 测试后端(Test Backend):无需 DOM 完整模拟拖放交互的实战指南

原创2026-09-19 13:17:051,934 阅读
文章标签:前端UI组件

react-dnd 测试后端(Test Backend):无需 DOM 完整模拟拖放交互的实战指南

React DnD 的 Test Backend(测试后端)让你可以在完全没有 DOM 与浏览器事件系统的环境下,驱动并验证完整的拖放交互流程。本文以官方文档 Test.md 为主线,结合仓库内 react-dnd-test-backend 包的源码与真实测试用例,系统讲解它的安装方式、simulate* 模拟方法 API、wrapWithTestBackend 便捷封装,以及如何用它编写可自动化运行的集成测试。

什么是 Test Backend

React DnD 采用“后端(Backend)抽象”架构:渲染层(react-dnd)与交互层(dnd-core)不直接依赖浏览器,而是通过 Backend 接口与具体实现解耦。生产环境中常用 HTML5 后端 监听真实的 dragstart、dragover、drop 等事件;而在测试环境下,这些事件无法轻易在 jsdom 中模拟(jsdom 缺少 DragEvent 与 DataTransfer 对象)。

Test Backend 正是为此设计的替身:它不依赖任何 DOM,直接调用 dnd-core 的 action 来“播放”一次拖放交互的完整状态机,包括 begin drag、hover、drop、end drag 四个阶段。因此你可以在 Jest、Mocha 等任何测试运行器中使用它,甚至配合 React 的浅渲染(Shallow Rendering)使用。

Test Backend 单独发布为一个 npm 包 react-dnd-test-backend,对应仓库目录为 packages/backend-test,其源码由三部分构成:

  • TestBackend.ts:TestBackendImpl 类,实现 Backend 与 ITestBackend 双接口;
  • types.ts:ITestBackend、TestBackendContext、TestBackendOptions 类型定义;
  • index.ts:导出 TestBackend 工厂函数。

安装 Test Backend

官方文档给出的安装命令为:

npm install -D react-dnd-test-backend

注意 -D 表示安装为开发依赖(devDependencies),因为测试后端只服务于测试代码,不应进入生产包。当前仓库中该包的版本为 16.0.1(见 packages/backend-test/package.json),它仅依赖 dnd-core(工作区引用 workspace:^),不依赖 React,也不依赖任何浏览器 API。

如果使用 Yarn,可以等价地执行:

yarn add -D react-dnd-test-backend

安装完成后,从包中导入 TestBackend 工厂函数即可开始使用。

基本用法:把 TestBackend 接入 DndProvider

Test Backend 与生产后端的使用方式完全一致——通过 DndProvider 的 backend 属性注入。官方文档说明其用法参见 Testing 教程 中的第二个示例(“Testing the Drag and Drop Interaction”章节)。下面是一个最小可用示例,直接用 DndProvider 包裹被测组件:

import { render } from '@testing-library/react'
import { DndProvider } from 'react-dnd'
import { TestBackend } from 'react-dnd-test-backend'
import { useDrag, useDrop } from 'react-dnd'

function DraggableBox() {
  const [, drag] = useDrag(() => ({ type: 'box' }))
  return <div ref={drag} role="box" />
}

it('可以在 TestBackend 环境下渲染拖放组件', async () => {
  const result = render(
    <DndProvider backend={TestBackend}>
      <DraggableBox />
    </DndProvider>,
  )
  expect(await result.findByRole('box')).toBeDefined()
})

这与仓库自身的测试写法完全一致:在 useDrag.spec.tsx 和 useDrop.spec.tsx 中,测试代码都通过 <DndProvider backend={TestBackend}> 挂载被测 Hook,用于验证“渲染在 React-DnD 上下文之外会抛出 Expected drag drop context”“type 未定义会抛出 spec.type must be defined”等行为。

深入源码:TestBackend 工厂与 simulate* 方法族

Test Backend 的核心价值在于 ITestBackend 暴露的 simulate* 方法族。在 TestBackend.ts 中可以看到,TestBackendImpl 的构造器接收 DragDropManager,并通过 manager.getActions() 拿到 dnd-core 暴露的 action 集合,随后每个 simulate* 方法都只是对该 action 的一层薄封装:

模拟方法 底层 action 作用
simulateBeginDrag(sourceIds, options) actions.beginDrag 启动一次拖放,sourceIds 为发起拖拽的 drag source 的 handler id 数组
simulatePublishDragSource() actions.publishDragSource 发布拖拽源(将 source 信息写入 monitor)
simulateHover(targetIds, options) actions.hover 模拟拖拽指针悬停到目标之上,targetIds 为 drop target 的 handler id 数组
simulateDrop() actions.drop 在目标上执行放置
simulateEndDrag() actions.endDrag 结束本次拖拽

对应的 ITestBackend 类型定义在 packages/backend-test/src/types.ts,其中 simulateBeginDrag 与 simulateHover 的 options 为可选参数(类型标注为 any),可用于传递坐标等额外信息:

export interface ITestBackend extends Backend {
  didCallSetup: boolean
  didCallTeardown: boolean
  simulateBeginDrag(sourceIds: Identifier[], options?: any): void
  simulatePublishDragSource(): void
  simulateHover(targetIds: Identifier[], options?: any): void
  simulateDrop(): void
  simulateEndDrag(): void
}

此外 ITestBackend 还保留了生命周期标记属性 didCallSetup 与 didCallTeardown,分别对应 setup() / teardown() 是否被调用过。这两个方法由 dnd-core 的 DragDropManagerImpl.ts 中的 handleRefCountChange 驱动:当注册的 source/target 引用计数从 0 变为正数时调用 backend.setup(),反之调用 backend.teardown()。TestBackend 只是把标记位置为 true,不做任何 DOM 工作。

TestBackend 本身是一个 BackendFactory 类型的工厂函数(见 packages/backend-test/src/index.ts):

export const TestBackend: BackendFactory = function createBackend(
  manager: DragDropManager,
  context: TestBackendContext = {},
  options: TestBackendOptions = {},
): ITestBackend {
  const result = new TestBackendImpl(manager, context)
  if (options?.onCreate) {
    options.onCreate(result)
  }
  return result
}

其中 TestBackendOptions.onCreate 是一个重要的回调:它在后端实例创建后立即触发,并把你拿到手的后端实例回传出来。这正是“如何在测试代码里取得 backend 实例”的关键机制——onCreate 回调中把实例保存到闭包变量,测试体即可调用 simulate* 方法。

便捷封装:wrapWithTestBackend 与 wrapWithBackend

官方 Testing 教程中的经典写法 wrapInTestContext(Box) 在当前仓库中已演进为 react-dnd-test-utils 包提供的 wrapWithTestBackend。该工具位于 packages/test-utils/src/wrappers.tsx,它把“用 DndProvider 包裹组件 + 通过 onCreate 取出 backend”这两步封装成一个函数:

export function wrapWithTestBackend<T>(
  DecoratedComponent: ComponentType<T>,
): [ComponentType<T>, () => ITestBackend | undefined] {
  let backend: ITestBackend | undefined
  const opts: TestBackendOptions = {
    onCreate(be) {
      backend = be
    },
  }
  const result = wrapWithBackend(DecoratedComponent, TestBackend, opts)
  return [result, () => backend]
}

用法与文档示例一致:

import { wrapWithTestBackend } from 'react-dnd-test-utils'
import Box from './components/Box'

it('can be tested with the testing backend', () => {
  const [BoxContext, getBackend] = wrapWithTestBackend(Box)
  const root = TestUtils.renderIntoDocument(<BoxContext name="test" />)

  // 找到 drag source 的 handler id 并模拟拖拽开始
  const box = TestUtils.findRenderedComponentWithType(root, Box)
  getBackend().simulateBeginDrag([box.getHandlerId()])

  // 验证组件在拖拽中的状态变化(如透明度变化)
  // ...
})

wrapWithTestBackend 返回一个二元组:第一个元素是被包裹后的组件(内部用 <DndProvider backend={TestBackend} options={opts}> 渲染),第二个元素是一个 getBackend() 函数,用于在测试体中随时取回 backend 实例。底层实现 wrapWithBackend 还支持传入任意 BackendFactory,例如默认回退到 HTML5Backend,因此也可以用它配合其他后端编写基于真实 DOM 事件的测试。

编写完整的拖放集成测试

官方 Testing 教程强调:Test Backend 不要求浏览器事件系统,因此适用于“测试整个交互而非单个组件渲染”的场景。一次标准拖放交互的测试序列是:

getBackend().simulateBeginDrag([sourceId])
getBackend().simulateHover([targetId])
getBackend().simulateDrop()
getBackend().simulateEndDrag()

仓库 packages/test-utils/src/eventSimulation.ts 把这段序列封装成了 simulateDragDrop 辅助函数,并额外提供了 simulateDragHover(只做 begin + hover)和 simulateDrag(只做 begin),且整个模拟过程包裹在 act() 中以确保 React 状态更新被正确冲刷:

export function simulateDragDrop(
  source: HandlerIdProvider,
  target: HandlerIdProvider,
  backend: ITestBackend,
): void {
  const sourceHandlerId = getHandlerId(source)
  const targetHandlerId = getHandlerId(target)
  act(() => {
    backend.simulateBeginDrag([sourceHandlerId])
    backend.simulateHover([targetHandlerId])
    backend.simulateDrop()
    backend.simulateEndDrag()
  })
}

getHandlerId 兼容两种 handler id 提供方式:直接传入字符串/Symbol,或传入返回 id 的函数(组件实例暴露的 getHandlerId() 方法即属此类)。

仓库中一个真实的端到端示例是 packages/examples/src/01-dustbin/single-target/tests/single-target-integration.spec.tsx,它验证了“把 Glass 拖入垃圾桶后弹出正确提示”的完整交互:

import { fireDragDrop, wrapWithBackend } from 'react-dnd-test-utils'
import Example from '../index.js'

it('can simulate a full drag and drop interaction', async () => {
  const TestExample = wrapWithBackend(Example)
  const rendered = render(<TestExample />)
  window.alert = jest.fn()
  const box = (await rendered.findAllByTestId('box'))[0]
  const dustbin = (await rendered.findAllByTestId('dustbin'))[0]

  await fireDragDrop(box!, dustbin)
  expect(window.alert).toHaveBeenCalledWith('You dropped Glass into Dustbin!')
})

这里先用 wrapWithBackend(Example) 把示例组件包进 TestBackend 环境,再用 fireDragDrop(box, dustbin) 完成一次完整拖放,最后断言 window.alert 收到的消息——整个测试不依赖任何真实的拖拽事件,却完整覆盖了从拖动到放置的业务逻辑。

与 HTML5/Touch 后端测试的取舍

Test Backend 并非唯一测试路径,官方文档(Testing 教程)也给出了另外两种思路,可据此选择:

  1. 组件隔离渲染测试:不测交互,仅用 DecoratedComponent 静态属性取出原始类,用恒等函数 stub 掉 connector 方法即可,完全脱离 React DnD。
  2. 基于 jsdom 的真实 DOM 事件测试:使用 HTML5 后端 或 Touch 后端配合 jsdom,用 fireEvent.dragStart / fireEvent.drop 等触发事件。需要注意 jsdom 没有 DragEvent 与 DataTransfer,会影响拖拽预览图与文件拖拽相关测试,且事件对象不含元素宽度、坐标等渲染相关属性,需要自行补充。

Test Backend 的优势在于:不依赖事件系统、无需补齐 DataTransfer、运行稳定且速度快,适合把业务逻辑(如 source/target 的 type 匹配、drop 副作用)与浏览器细节彻底解耦后进行验证。若需深入了解 dnd-core 层 action 与状态机如何驱动这些 simulate* 方法,可继续阅读 dnd-core 的 actions 目录 及其 Redux reducer 实现。

小结

  • 安装:npm install -D react-dnd-test-backend,仅作为开发依赖使用;
  • 接入:<DndProvider backend={TestBackend}> 与生产后端写法一致;
  • 模拟:通过 simulateBeginDrag → simulateHover → simulateDrop → simulateEndDrag 四步播放完整拖放流程;
  • 取回实例:利用 TestBackendOptions.onCreate 回调或 wrapWithTestBackend 返回的 getBackend();
  • 进阶:react-dnd-test-utils 提供了 simulateDragDrop、fireDragDrop 等封装,配合 act() 保证 React 更新冲刷,可直接复用于你的集成测试。
登录后查看全文
react-dnd