From 3f89381ac3f7a9ebfb1dee7d3b1808d3f0c6351c Mon Sep 17 00:00:00 2001 From: eps1lon Date: Sat, 14 Jan 2023 09:19:03 +0100 Subject: [PATCH] Add docs for Web Testing Library --- docs/web-testing-library/api.mdx | 57 ++++++++++++++++++++ docs/web-testing-library/faq.mdx | 18 +++++++ docs/web-testing-library/install.mdx | 80 ++++++++++++++++++++++++++++ docs/web-testing-library/intro.mdx | 36 +++++++++++++ sidebars.js | 8 +++ 5 files changed, 199 insertions(+) create mode 100644 docs/web-testing-library/api.mdx create mode 100644 docs/web-testing-library/faq.mdx create mode 100644 docs/web-testing-library/install.mdx create mode 100644 docs/web-testing-library/intro.mdx diff --git a/docs/web-testing-library/api.mdx b/docs/web-testing-library/api.mdx new file mode 100644 index 000000000..ed6ec4d9a --- /dev/null +++ b/docs/web-testing-library/api.mdx @@ -0,0 +1,57 @@ +--- +id: api +title: API +--- + +Several utilities are provided for dealing with asynchronous code. These can be +useful to wait for an element to appear or disappear in response to an event, +user action, timeout, or Promise. (See the +[guide to testing disappearance](guide-disappearance.mdx).) + +The async methods return Promises, so be sure to use `await` or `.then` when +calling them. + +## `waitFor` + +```typescript +function waitFor( + callback: () => T | Promise, + options?: { + timeout?: number + interval?: number + onTimeout?: (error: Error) => Error + }, +): Promise +``` + +When in need to wait for any period of time you can use `waitFor`, to wait for +your expectations to pass. Here's a simple example: + +```javascript +// ... +// Wait until the callback does not throw an error. In this case, that means +// it'll wait until the mock function has been called once. +await waitFor(() => expect(mockAPI).toHaveBeenCalledTimes(1)) +// ... +``` + +`waitFor` may run the callback a number of times until the timeout is reached. +Note that the number of calls is constrained by the `timeout` and `interval` +options. + +This can be useful if you have a unit test that mocks API calls and you need to +wait for your mock promises to all resolve. + +If you return a promise in the `waitFor` callback (either explicitly or +implicitly with `async` syntax), then the `waitFor` utility will not call your +callback again until that promise rejects. This allows you to `waitFor` things +that must be checked asynchronously. + +The default `interval` is `50ms`. However it will run your callback immediately +before starting the intervals. + +The default `timeout` is `1000ms`. + +The default `onTimeout` takes the error and appends the `container`'s printed +state to the error message which should hopefully make it easier to track down +what caused the timeout. diff --git a/docs/web-testing-library/faq.mdx b/docs/web-testing-library/faq.mdx new file mode 100644 index 000000000..d738a21ed --- /dev/null +++ b/docs/web-testing-library/faq.mdx @@ -0,0 +1,18 @@ +--- +id: faq +title: FAQ +--- + +
+ +Why "Web" in "Web Testing Library + +This library implements testing utilities that are used on different clients +implementing the +[Minimum Common Web Platform API](https://proposal-common-min-api.deno.dev/) (or +parts of it). This includes browsers, Node.js, Deno and React Native. + +React Native is included for pragmatic reasons. In the future, we might split +the utilities up in Web and Timer testing utilities. + +
diff --git a/docs/web-testing-library/install.mdx b/docs/web-testing-library/install.mdx new file mode 100644 index 000000000..e58f09a32 --- /dev/null +++ b/docs/web-testing-library/install.mdx @@ -0,0 +1,80 @@ +--- +id: install +title: Install +sidebar_label: Install +--- + +This module is distributed via [npm][npm] and should be installed as one of your +project's `devDependencies`: + +``` +npm install --save-dev @testing-library/web +``` + +## Wrappers + +If you are using a framework or library such as React, you will likely want to +install the wrapper: + +- [React Testing Library](react-testing-library/intro.mdx) +- [Reason Testing Library](bs-react-testing-library/intro.mdx) +- [React Native Testing Library](react-native-testing-library/intro.mdx) +- [Vue Testing Library](vue-testing-library/intro.mdx) +- [Marko Testing Library](marko-testing-library/intro.mdx) +- [Angular Testing Library](angular-testing-library/intro.mdx) +- [Preact Testing Library](preact-testing-library/intro.mdx) +- [Svelte Testing Library](svelte-testing-library/intro.mdx) +- [Cypress Testing Library](cypress-testing-library/intro.mdx) +- [Puppeteer Testing Library](pptr-testing-library/intro.mdx) +- [Testcafe Testing Library](testcafe-testing-library/intro.mdx) +- [Nightwatch Testing Library](nightwatch-testing-library/intro.mdx) + +## Ecosystem + +`Web Testing Library` works well with these companion libraries: + +- [user-event](user-event/intro.mdx) browser event simulation +- [jest-dom](ecosystem-jest-dom.mdx) custom Jest matchers +- [bs-jest-dom](ecosystem-bs-jest-dom.mdx) companion library for + `bs-react-testing-library` +- [jest-native](ecosystem-jest-native.mdx) companion library for + `React Native Testing Library` +- [react-select-event](ecosystem-react-select-event.mdx) companion library for + `React Testing Library` +- [eslint-plugin-testing-library](ecosystem-eslint-plugin-testing-library.mdx) + ESLint plugin for Testing Library +- [eslint-plugin-jest-dom](ecosystem-eslint-plugin-jest-dom.mdx) ESLint plugin + for Jest DOM +- [riot-testing-library](ecosystem-riot-testing-library.mdx) adds APIs for + working with Riot.js components + +## Main Exports + +You can +[review the `Web Testing Library` package.json here](https://unpkg.com/@testing-library/web/package.json). + +In particular, the `main`, `module`, and `umd:main` fields are useful. Each of +these points to a file that's useful in certain situations. Typically, your +testing framework will resolve to the correct one for your situation, but if it +does not, then you can either configure your testing framework to resolve to the +right file when you require/import `@testing-library/dom` or you can import the +file you need more explicitly. For example: + +```js +import {waitFor} from '@testing-library/web/dist/@testing-library/web.umd.js' +``` + +You can +[review the published `dist` files here](https://unpkg.com/@testing-library/web/dist/). + +The `main` file is configured to compile down to support the version of node +that is referenced in the `package.json` `engines.node` field. But the `module` +and `umd:main` files are configured to compile down to support browsers as old +as IE 10. + + + +[npm]: https://www.npmjs.com/ +[node]: https://nodejs.org diff --git a/docs/web-testing-library/intro.mdx b/docs/web-testing-library/intro.mdx new file mode 100644 index 000000000..deb2c8b2c --- /dev/null +++ b/docs/web-testing-library/intro.mdx @@ -0,0 +1,36 @@ +--- +id: intro +title: Introduction +--- + +## The problem + +You want to write maintainable tests for the +[Web Platform](https://proposal-common-min-api.deno.dev/) or React Native. As a +part of this goal, you want your tests to avoid including implementation details +of your components and rather focus on making your tests give you the confidence +for which they are intended. As part of this, you want your testbase to be +maintainable in the long run so refactors of your components (changes to +implementation but not functionality) don't break your tests and slow you and +your team down. + +## This solution + +The `Web Testing Library` is a very light-weight solution for testing code that +runs on the Web Platform (a browser, [Node.js][node], [Deno](https://deno.land/) +etc) or React Native. The main utilities it provides involve querying the DOM +for nodes in a way that's similar to how the user finds elements on the page. In +this way, the library helps ensure your tests give you confidence in your UI +code. The `DOM Testing Library`'s primary guiding principle is: + +> [The more your tests resemble the way your software is used, the more +> confidence they can give you.][guiding-principle] + +**What this library is not**: + +1. A test runner or framework +2. Specific to a testing framework (though we do have better defaults for Jest + like support for fake timers). + +[jest]: https://jestjs.io +[node]: https://nodejs.org/en/ diff --git a/sidebars.js b/sidebars.js index 1b65be862..3202cc2a7 100755 --- a/sidebars.js +++ b/sidebars.js @@ -162,6 +162,14 @@ module.exports = { 'svelte-testing-library/api', ], }, + { + 'Web Testing Library': [ + 'web-testing-library/intro', + 'web-testing-library/install', + 'web-testing-library/api', + 'web-testing-library/faq', + ], + }, 'cypress-testing-library/intro', 'pptr-testing-library/intro', 'testcafe-testing-library/intro',