深入浅出 testing-library

我们是袋鼠云数栈 UED 团队,致力于打造优秀的一站式数据中台产品。我们始终保持工匠精神,探索前端道路,为社区积累并传播经验价值。

本文作者:佳岚

The more your tests resemble the way your software is used, the more confidence they can give you.
您的测试越接近软件的使用方式,它们就越能给您带来信心。

什么是 testing-library?

在了解 testing-library 前,我们可以看看使用原生方法是如何进行 React 组件测试的。

import Header from ".."
import client from 'react-dom/client'
import  { act } from 'react-dom/test-utils'

let container;
beforeEach(() => {
    container = document.createElement('div');
    document.body.appendChild(container)
});
afterEach(() => {
    document.body.removeChild(container);
    container = null;
})
test('test render', () => {
    act(() => {
        client.createRoot(container!).render(<Header />)
    });
    const button = container!.querySelector('button');
    const count = container!.querySelector("span[title='count']");

    act(() => {
        button?.dispatchEvent(new MouseEvent("click", { bubbles: true }));
        // or Simulate.click(button!)
    });
    expect(count?.textContent).toEqual('1')
})

在上面案例中,我们需要自行创建一个根容器来渲染 React 组件, 且我们必须及时清除该根容器,避免对其他测试用例产生影响。
在 Header 组件中,我们每次点击按钮都会进行计数+1,当我们要进行点击时,需要自行创建事件实例,且由于合成事件的原因需要增加 bubbles 属性,这使得对开发者也就有了些许能力要求。
除此之外,事件触发必须包裹在 act 方法中,render 方法中相同。

什么是 act ?

正常情况下,我们的单测代码是同步执行的,即代码执行完毕则单测完成。React 中的渲染并不是同步的,当我们进行事件触发,导致了 rerender 后,并不能立马获取新的页面结果,导致后续的断言失败。act 是由 React 官方在 react-dom/test-utils 中提供的一个方法,它能够让回调函数调用后,立即执行 React 内部 pending 中的异步队列。

我们再使用 RTL 去实现代码,RTL 为我们简化了 render 所需要的重复模板代码,模拟事件也不再需要包裹 act ,并提供了通用的查询方法。

test('test by RTL', () => {
    const { getByRole, getByTitle } = render(<Header />);
    const button = getByRole("button")
    const count = getByTitle('count')
    fireEvent.click(button);
    expect(count.textContent).toEqual('1');
})

设计理念

testing-library 是以用户为中心 的方式进行 UI 组件的测试。什么是 以用户为中心
即以用户的角度方式去审视你的 UI 组件,用户是不关心你的组件内部是如何实现的,只关心最终的功能效果是否正确。你不应该在 testing-library 中去测试组件的 props 与内部 state,生命周期等是否正确。
Why ?

组成架构

testing-library 的核心部分是 DOM Testing Library@testing-library/dom , 它提供了通用的DOM 查询功能,如getByRole getByText 与事件行为的基本实现。

在此基础上,再衍生出各自框架的专有包,如React Testing LibraryVue Testing Library ,对于不同的前端框架,其使用方法是基本一致的, 提供不同实现方式的 renderfireEvent 方法。
除了每个前端框架提供各自的 fireEvent 接口外,还额外提供了一个@testing-library/user-event的通用包,不依赖于所选框架实现,它能够对用户事件的真实模拟,下文会详细说到。

除此之外,还针对 Jest 测试框架开发了一个断言库 @testing-library/jest-dom ,如我们平常经常使用的 expect().toBeInTheDocument() 就是该库为我们实现的,其通过 jest 提供的自定义断言器expect.extend(matchers) 将断言库注入到我们所使用的的 jest 上下文中

查询方法

查询作为testing-library的核心,它主要以用户的角度去查询,如根据组件展示的文字,Title 等信息。

查询内容

从查询内容上来讲它提供了8种类型

  1. ByRole
    通过可访问性、语义化查询元素, 如checkbox, menu, navigation , 对于实际场景并不常用。

  2. ByLabelText
    通过 label 找到 label 所对应的元素,通常在表单中使用,如下

render(
  <label>
    username
    <input />
  </label>
);
const el = screen.getByLabelText('username');
expect(el.tagName).toBe('INPUT')
  1. ByPlaceHolder
    通过占位符查询元素,当查询表单元素等,但又没有 label 标识的话,可以使用这个,但不推荐。

  2. ByText
    最常用的查询方法,根据 textContent 进行查询,通常可配合正则一起使用,如下

render(<div>Text Content is: 1</div>);
const el = screen.getByText(/Text Content is/);
expect(el.textContent).toBe("Text Content is: 1");
  1. ByDisplayValue
    通过数值进行查询包含该值的元素,如 input 与 select 会有 value 属性
const {container} = render(
    <div>
    <select>
        <option value="state">state</option>
        <option value="prop">prop</option>
    </select>
    </div>
);
const select = container.querySelector('select')!;
select.value = 'state'
const el = screen.getByDisplayValue('state');
expect(el).toEqual(select)
  1. ByAltText
    根据 alt 属性进行查询,如<img alt=”img1” src=”xxx” />

  2. ByTitle
    根据 title 属性进行查询,同上

  3. ByTestId
    如果以上查询方式都不容易查询到节点,则最终可以考虑 testid,这种方式会侵入源代码,但不会对页面效果产生影响,通过在元素上添加 data-testid 属性来查询,查询时相当于container.querySelector([data-testid="${yourId}"])

有这么多方式,我该选哪个最好?

官方推荐优先使用用户页面可视的查询方式,如 byRole, byText 等可以在页面上看到的;其次是语义话查询方式,byAltTextByTitle ,这是在页面上基本看不到,但是易于机器读懂的;最后才应该考虑byTestId 。如果 byTestId 也无法实现,那你只是使用原生的 querySelector 也没什么问题

查询方式

testing-library 一共提供了三种查询类型getByfindByqueryBy ,这三种类型定义了对查询结果的处理方式。

通过 getBy 方式查询, 当查询不到元素时会直接抛出一个错误, 则导致测试失败。

我们看看下面这个案例,上面部分额外的显式使用了断言,其运行结果最终是一模一样的。

但应该采用哪种写法最好?

test("test getBy with assertion", () => {
    const { getByRole } = render(
        <div>
            <button>按钮</button>
        </div>
    );
    expect(getByRole("list")).toBeInTheDocument();
});

test("test getBy", () => {
    const { getByRole } = render(
        <div>
            <button>按钮</button>
        </div>
    );
    getByRole("list")
});

如果这段测试的意义是为了测试元素是否存在,则最佳实践应是采用使用显式断言的方式。

通过 queryBy 方式查询,与 getBy 的唯一不同就是查询不到元素时不会抛出错误。

那么什么情况下该使用 queryBy 还是 findBy

事实上,绝大多数情况下应直接使用 getBy ,只在想测试元素不存在这种场景时使用 queryBy

test("test queryBy", () => {
    const { queryByRole } = render(
        <div>
            <button>按钮</button>
        </div>
    );
    expect(queryByRole("list")).not.toBeInTheDocument()
});

通过 findBy 进行查询,他与 getBy  一致,查询不到时会抛出错误,但是它能够用来查询异步元素。

何为异步元素?

在前面我们讲过,setState 导致的异步渲染,我们已经通过React提供的 act 方法解决了,对于某些场景,比如上传文件后,显示已上传的文件列表,上传文件操作是异步的,我们需要在一定时间后才能拿到文件列表元素;又或者说 setTimeout 或者promise 中进行了setState 操作,渲染的元素也需要异步获取。

在讲 findBy 之前,我们先了解下 waitFor , waitFor 也是testing-library 提供的一个异步方法,它提供了一种对于不确定代码运行时间的处理方法。在使用时,必须使单测块变为异步的,否则就没了使用意义,因此 waitFor 一般都与 await 一起使用。

使用方式如下:

test("test waitFor", async () => {
    const Foo = () => {
        const [text, setText] = useState('text1')
        useEffect(() => {
            setTimeout(() => {
                setText('text2')
            }, 300);
        }, [])
        return <span>{text}</span>
    }

    const { getByText } = render(<Foo />);
    await waitFor(() => {
        expect(getByText('text2')).toBeInTheDocument()
    })
})

其原理也很简单,不断的去执行传入的回调函数,直到回调函数没有抛出错误或者超出最大等待时间。expect 断言失败,本质上也是抛出个错误, 因此一般会把断言写在 waitFor 中。

waitFor 默认超时时间为1000ms,每50ms执行一次回调。但在测试环境我们也不可能真去等1秒时间,其内部做了额外处理。

  1. 默认会优先采用jestfakeTimers 来略过时间等待,但这个前提是在执行 waitFor 前,需要进行 fakeTimers 的注册,也就是执行 jest.useFakeTimers()
    但很多情况下我们是没有使用 fakerTimers , 且 testing-library 是测试框架无关的,所以在其他情况下会使用MutationObserver 来作为重复执行 callback 的时机。
  2. 在循环开始前会添加一个超时时间的定时器 overallTimeoutTimer ,定时器回调被调用则说明超时,直接 reject 掉。
  3. 当采用 fakeTimers 方案时,会在每次循环时通过 jest.advanceTimersByTime 等待一定的时间interval(并非真正的等待)
  4. checkCallback 方法中,会调用 callback ,并进行异常捕获,如捕获到异常则会进行下一次的循环,如果正常则在 onDone 方法中将 finished 置为 true ,并结束当前promise。
  5. 当使用 MutationObserver 方案时,会监听 document DOM 节点的变化(包括其自己节点)。除此之外,由于 MutationObserver 是监听DOM树来实现的,某些场景会有限制,如 CSS 属性的变化,因此还会启用一个 setInterval 原始的定时器来做辅助执行,保证回调一定会被执行。
function waitFor(
  callback,
  {
    container = getDocument(),
    timeout = getConfig().asyncUtilTimeout,
    interval = 50,
    // 其他参数略
  },
) {
  return new Promise(async (resolve, reject) => {
    let lastError, intervalId, observer
    let finished = false
    let promiseStatus = 'idle'
		// 超时时间的timerid
    const overallTimeoutTimer = setTimeout(handleTimeout, timeout)
    const usingJestFakeTimers = jestFakeTimersAreEnabled()
    // 如果使用了jest的fakeTimers,则采用advanceTimersByTime快速略过时间
    if (usingJestFakeTimers) {
      const {unstable_advanceTimersWrapper: advanceTimersWrapper} = getConfig()
      checkCallback()
			// 不断的等待一定时间后并检测回调是否通过检测
      while (!finished) {
        await advanceTimersWrapper(async () => {
          jest.advanceTimersByTime(interval)
        })
				// 调用callback并检测是否跑错
        checkCallback()
        if (finished) {
          break
        }
      }
    } 
    // 如果没有使用fakeTimers,则退化为使用MutationObserver观测元素变化时执行一遍
    else {
      intervalId = setInterval(checkRealTimersCallback, interval)
      const {MutationObserver} = getWindowFromNode(container)
      observer = new MutationObserver(checkRealTimersCallback)
      observer.observe(container, mutationObserverOptions)
      checkCallback()
    }

		function checkCallback() {
      if (promiseStatus === 'pending') return
      try {
        const result = callback()
				// 处理callback为异步函数的情况
        if (typeof result?.then === 'function') {
          promiseStatus = 'pending'
          result.then(
            resolvedValue => {
              promiseStatus = 'resolved'
              onDone(null, resolvedValue)
            },
            rejectedValue => {
              promiseStatus = 'rejected'
              lastError = rejectedValue
            },
          )
        } else {
          onDone(null, result)
        }
      } catch (error) {
        lastError = error
      }
    }

    function onDone(error, result) {
      finished = true
      clearTimeout(overallTimeoutTimer)

      if (!usingJestFakeTimers) {
        clearInterval(intervalId)
        observer.disconnect()
      }

      if (error) {
        reject(error)
      } else {
        resolve(result)
      }
    }
}

从源码中看其实现还是很巧妙的,额外还需要注意的点是,回调函数是支持传入 async 函数的,当传入 async 函数时,会等待 promise 状态改变后才会再次执行。

再回到 findBy , 它其实就是对 waitFor 的一个封装,类似于下面这种代码。

await waitFor(() => getByXXX())

在使用时也必须加上 await 关键字,并且当你想要使用 findBy 时,请确保元素最终一定会存在,如果你想要测试元素是否存在,请使用waitFor + expect的形式保证其具有足够的语义。

test("test findBy", async () => {
    const Foo = () => {
        const [text, setText] = useState('text1')
        useEffect(() => {
            setTimeout(() => {
                setText('text2')
            }, 300);
        }, [])
        return <span>{text}</span>
    }

    const { findByText } = render(<Foo />);
    const span = await findByText('text2');
    expect(span.nodeName).toBe('SPAN')
})

除此之外,所有查询方法都是严格区分数量的,如果查询结果数量返回大于1,即使是 queryBy 类型,也会报错导致测试失败,对于多个返回的,需要使用getAllBy, queryAllBy, findAllBy
贴一张文档上的区别图

事件触发

testing-library 提供了两种触发事件的方式,fireEventuserEvent

fireEvent

fireEvent是从 React Testing LIbrary 中引入的,其内部又是基于 DOM Testing Library 的 fireEventReact 做了一些兼容性改动。
其使用方式非常方便, 有 fireEvent(node, event) 或者 fireEvent(node, eventProperties) 两种使用方式

fireEvent.change(getByLabelText(/picture/i), {
  target: {
    files: [new File(['(⌐□_□)'], 'chucknorris.png', {type: 'image/png'})],
  },
});

fireEvent(getByLabelText(/picture/i), new Event('change', 
	{bubbles: true, cancelable: false})
);

在 DOM Testing Library 中 fireEvent 的实现, 也是通过 dispatchEvent 来做的

function fireEvent(element, event) {
  return getConfig().eventWrapper(() => {
    if (!event) {
      throw new Error(
        `Unable to fire an event - please provide an event object.`,
      )
    }
    if (!element) {
      throw new Error(
        `Unable to fire a "${event.type}" event - please provide a DOM element.`,
      )
    }
    return element.dispatchEvent(event)
  })
}

那我们看看 React Testing Library 中又做了啥,它其实是对 fireEvent 加了层 act 包裹,这也是我们能直接使用的原因, fireEvent 时切记不要再手动包裹 act

configureDTL({
  eventWrapper: cb => {
    let result
    act(() => {
      result = cb()
    })
    return result
  },
	// 略
})

我们实际开发中经常会时不时的遇到 act 的飘红报错,看到报错提示我们不经意间就加了个 act上去,但这样其实是没用的。

比如下面这个案例:

test("test act warning", () => {
    const Foo = () => {
        const [text, setText] = useState('text1')
        useEffect(() => {
            Promise.resolve().then(() => setText('text2'))
        }, [])
        return <div>
                <span>{text}</span>
                <div>haha</div>
            </div>
    }

    const { getByText, debug } = render(<Foo />);
    const text = getByText('haha');
    expect(text).toBeInTheDocument()
    debug()
})

当我们代码中进行异步请求时,并在测试完成后或者 act 执行完成后,再在回调中进行 setState 则会导致报错。

上面这段代码想要修复报错,有很多方式,如可以在测试结束前进行等待来解决,或者直接干脆把异步请求的返回mock掉,不进行setState

优化后的代码

test("test act warning", async () => {
    const Foo = () => {
        const [text, setText] = useState('text1')
        const fn = 
        useEffect(() => {
            Promise.resolve().then(() => setText('text2'))
        }, [])
        return <div>
                <span>{text}</span>
                <div>haha</div>
            </div>
    }

    const { getByText, findByText } = render(<Foo />);
    const text = getByText('haha');
    expect(text).toBeInTheDocument()
		// 等待后再结束测试
    await findByText('text2')
})

又或者使用异步的act , 在初次 render 时 手动包裹一层 act , act 是支持嵌套使用的。这在初始化组件时请求异步数据很有用

await act(async () => render(<Foo />) )
const text = screen.getByText('text2');
expect(text).toBeInTheDocument()

如果我再加入个异步任务,结果又如何?

useEffect(() => {
  Promise.resolve().then(() => setText('text2')).then(() => setText('text3'))
}, [])

答案是:tex3

userEvent

userEvent是 testing library 的单独一个测试包,需要从@testing-library/user-event中引入。

fireEvent 不同的是,该包是完全以模拟用户的真实行为去触发事件的。

fireEvent是浏览器低级dispatchEventAPI 的轻量级包装器,它允许开发人员触发任何元素上的任何事件。问题在于,浏览器通常不仅仅为一次交互触发一个事件。例如,当用户在文本框中键入内容时,必须聚焦该元素,然后触发键盘的输入事件。userEvent 其实就是真实模拟了用户使用时的交互方式。

下面是个简单的输入案例。

test("test userEvent", async () => {
    const onChange = jest.fn();
    const onFocus = jest.fn();
    const onClick = jest.fn();
    const { getByPlaceholderText } = render(
        <input
            placeholder="请输入"
            type="textarea"
            onChange={onChange}
            onFocus={onFocus}
            onClick={onClick}
        />
    );
    const input = getByPlaceholderText("请输入");
    await userEvent.type(input, 'hello');
    expect(onChange).toHaveBeenCalled();
    expect(onFocus).toHaveBeenCalled();
    expect(onClick).toHaveBeenCalled();
    expect(input).toHaveDisplayValue('hello')
})

需要注意的是,userEvent由于模拟了一系列操作,需要以异步的形式调用才能获取结果。

userEvent 还提供了很多其他的模拟操作,如复制粘贴,模拟键盘打字,模拟文件上传等等用户交互场景。

值得注意的是,testing-library 官方是推荐我们在大多数情况下应优先考虑使用 userEvent 而非 fireEvent 的,因为您的测试越接近软件的使用方式,它们就越能给您带来信心。

产品中的一些反模式

  1. 不要再在无用的地方加 cleanup 了**。

首先为何需要有 cleanup 清除函数?
在一个单测文件中我们可能有多个test ,每个测试实例渲染自己的组件,但是window.document 只有一个,每次 render() 都会往body下添加一个div作为根容器,我们保证测试自己的组件时 body 下是无子节点的避免影响。cleanup 会对当前所有挂载的React根组件进行unmount, 并移除对应的元素。

function cleanup() {
  mountedRootEntries.forEach(({root, container}) => {
    act(() => {
      root.unmount()
    })
    if (container.parentNode === document.body) {
      document.body.removeChild(container)
    }
  })
  mountedRootEntries.length = 0
  mountedContainers.clear()
}

为何不需要再 cleanup 了?RTL中自动帮我们调了。

何时才需要 cleanup

同一个测试块中,render 了多次使其挂载了多个组件根节点, 也就是在test代码块内进行调用。

  1. 错误的使用 waitFor
    waitFor 中语句要有抛错的能力才有实际意义
let el = null
await waitFor(() => {
    el = document.querySelector('.xxx')
})
await waitFor(() => {
    fireEvent.click(el);
		expect(el).toBeDisabled();
})
  1. fireEvent 包裹无意义的act
// 错误的
act(() => {
	fireEvent.click(el)
})

// 可能正确的方式
await act(async () => {
	fireEvent.click(el)
})

tips: 更多的反模式参考一些常见的RTL错误

参考:

https://www.robinwieruch.de/react-testing-library/
https://testing-library.com/docs/queries/about#priority

最后

欢迎关注【袋鼠云数栈UED团队】~
袋鼠云数栈 UED 团队持续为广大开发者分享技术成果,相继参与开源了欢迎 star

热门相关:萌妻太甜:总裁大人,别傲娇   士子风流   榴绽朱门   北宋大表哥   庶子风流