diff --git a/docs/pptr-testing-library/intro.md b/docs/pptr-testing-library/intro.md new file mode 100644 index 000000000..f99616cf6 --- /dev/null +++ b/docs/pptr-testing-library/intro.md @@ -0,0 +1,81 @@ +--- +id: intro +title: Puppeteer Testing Library +--- + +[`pptr-testing-library`][gh] is a lightweight adapter allowing +`dom-testing-library` to be used with [`puppeteer`][ghpuppeteer]. + +``` +npm install --save-dev puppeteer pptr-testing-library +``` + +- [pptr-testing-library on GitHub][gh] + +## Usage + +```js +const puppeteer = require('puppeteer') +const { getDocument, queries, wait } = require('pptr-testing-library') + +const { getByTestId, getByLabelText } = queries + +const browser = await puppeteer.launch() +const page = await browser.newPage() + +// Grab ElementHandle for document +const $document = await getDocument(page) +// Your favorite query methods are available +const $form = await getByTestId($document, 'my-form') +// returned elements are Puppeteer ElementHandles too! +const $email = await getByLabelText($form, 'Email') +// interact with puppeteer like usual +await $email.type('pptr@example.com') +// waiting works too! +await wait(() => getByText('Loading...')) +``` + +A little too un-puppeteer for you? You can attach all the `dom-testing-library` +methods directly onto puppeteer's `ElementHandle` instead! + +```js +const puppeteer = require('puppeteer') +require('pptr-testing-library/extend') + +const browser = await puppeteer.launch() +const page = await browser.newPage() + +// getDocument is added to prototype of Page +const $document = await page.getDocument() +// query methods are added directly to prototype of ElementHandle +const $form = await $document.getByTestId('my-form') +// destructing works if you explicitly call getQueriesForElement +const { getByLabelText } = $form.getQueriesForElement() +// ... +const $email = await getByLabelText('Email') +``` + +### API + +Unique methods, not part of `dom-testing-library`. + +- `getDocument(page: puppeteer.Page): ElementHandle` - get an ElementHandle for + the document + +### Forwarded methods + +`dom-testing-library` is injected into the page that puppeteer is controlling on +each query, so all results will be async. It's still recommended that you use +puppeteer's built-in methods for interaction rather than `fireEvent`. + +## Known Limitations + +- `waitForElement` method is not exposed. Puppeteer has its own set of wait + utilities that somewhat conflict with the style used in `dom-testing-library`. + See + [the issue on GitHub](https://github.com/patrickhulce/pptr-testing-library/issues/3). +- `fireEvent` method is not exposed, use puppeteer's built-ins instead. +- `expect` assertion extensions are not available. + +[gh]: https://github.com/patrickhulce/pptr-testing-library +[ghpuppeteer]: https://github.com/GoogleChrome/puppeteer diff --git a/website/pages/en/index.js b/website/pages/en/index.js index 7f0cdedaf..22204b939 100755 --- a/website/pages/en/index.js +++ b/website/pages/en/index.js @@ -210,6 +210,11 @@ class Index extends React.Component { title: '[ReasonReact Testing Library](./docs/bs-react-testing-library/intro)', }, + { + image: `${baseUrl}img/puppeteer-275x275.png`, + imageAlign: 'top', + title: '[Puppeteer Testing Library](./pptr)', + }, { image: `${baseUrl}img/construction-128x128.png`, imageAlign: 'top', diff --git a/website/pages/en/pptr.js b/website/pages/en/pptr.js new file mode 100644 index 000000000..df27475da --- /dev/null +++ b/website/pages/en/pptr.js @@ -0,0 +1,159 @@ +/** + * Copyright (c) 2017-present, Facebook, Inc. + * + * This source code is licensed under the MIT license found in the + * LICENSE file in the root directory of this source tree. + */ + +const React = require('react') + +const CompLibrary = require('../../core/CompLibrary.js') + +const MarkdownBlock = CompLibrary.MarkdownBlock /* Used to read markdown */ +const Container = CompLibrary.Container +const GridBlock = CompLibrary.GridBlock + +class HomeSplash extends React.Component { + render() { + const { siteConfig, language = '' } = this.props + const { baseUrl, docsUrl } = siteConfig + const docsPart = `${docsUrl ? `${docsUrl}/` : ''}` + const langPart = `${language ? `${language}/` : ''}` + const docUrl = doc => `${baseUrl}${docsPart}${langPart}${doc}` + + const SplashContainer = props => ( +
+
+
{props.children}
+
+
+ ) + + const Logo = props => ( +
+ Project Logo +
+ ) + + const ProjectTitle = () => ( +
+

Puppeteer Testing Library

+
+

+ Simple and complete Puppeteer DOM testing utilities that encourage + good testing practices +

+
+
+ ) + + const PromoSection = props => ( +
+
+
{props.children}
+
+
+ ) + + const Button = props => ( +
+ + {props.children} + +
+ ) + + return ( + + +
+ + + + +
+
+ ) + } +} + +class Index extends React.Component { + render() { + const { config: siteConfig, language = '' } = this.props + const { baseUrl } = siteConfig + + const Block = props => ( + + + + ) + + const FeatureCallout = () => ( + +
+

+ + The more your tests resemble the way your software is used,
+ the more confidence they can give you. +
+

+ + `npm install --save-dev pptr-testing-library` + +
+
+ ) + + const Features = () => ( + + + {[ + { + content: + 'Tests only break when your app breaks, not implementation details', + image: `${baseUrl}img/wrench-128x128.png`, + imageAlign: 'top', + title: 'Write Maintainable Tests', + }, + { + content: 'Interact with your app the same way as your users', + image: `${baseUrl}img/check-128x128.png`, + imageAlign: 'top', + title: 'Develop with Confidence', + }, + { + content: + 'Built-in selectors use semantic HTML and ARIA roles to help you write inclusive code', + image: `${baseUrl}img/tada-128x128.png`, + imageAlign: 'top', + title: 'Accessible by Default', + }, + ]} + + + ) + + return ( +
+ +
+ + +
+
+ ) + } +} + +module.exports = Index diff --git a/website/static/img/puppeteer-275x275.png b/website/static/img/puppeteer-275x275.png new file mode 100644 index 000000000..538a24311 Binary files /dev/null and b/website/static/img/puppeteer-275x275.png differ