feat: add pptr-testing-library docs (#36)

patrickhulce · alexkrolick · commit 7b487bd676b8 · 2019-02-16T11:54:37.000-08:00
diff --git a/docs/pptr-testing-library/intro.md 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
@@ -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
@@ -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 => (
+      <div className="homeContainer">
+        <div className="homeSplashFade">
+          <div className="wrapper homeWrapper">{props.children}</div>
+        </div>
+      </div>
+    )
+
+    const Logo = props => (
+      <div className="projectLogo">
+        <img src={props.img_src} alt="Project Logo" />
+      </div>
+    )
+
+    const ProjectTitle = () => (
+      <div>
+        <h2 className="projectTitle">Puppeteer Testing Library</h2>
+        <div className="projectTaglineWrapper">
+          <p className="projectTagline">
+            Simple and complete Puppeteer DOM testing utilities that encourage
+            good testing practices
+          </p>
+        </div>
+      </div>
+    )
+
+    const PromoSection = props => (
+      <div className="section promoSection">
+        <div className="promoRow">
+          <div className="pluginRowBlock">{props.children}</div>
+        </div>
+      </div>
+    )
+
+    const Button = props => (
+      <div className="pluginWrapper buttonWrapper">
+        <a className="button" href={props.href} target={props.target}>
+          {props.children}
+        </a>
+      </div>
+    )
+
+    return (
+      <SplashContainer>
+        <Logo img_src={`${baseUrl}img/puppeteer-275x275.png`} />
+        <div className="inner">
+          <ProjectTitle siteConfig={siteConfig} />
+          <PromoSection>
+            <Button href={docUrl('pptr-testing-library/intro')}>
+              Read the Docs
+            </Button>
+          </PromoSection>
+        </div>
+      </SplashContainer>
+    )
+  }
+}
+
+class Index extends React.Component {
+  render() {
+    const { config: siteConfig, language = '' } = this.props
+    const { baseUrl } = siteConfig
+
+    const Block = props => (
+      <Container
+        padding={['bottom', 'top']}
+        id={props.id}
+        background={props.background}
+      >
+        <GridBlock
+          align={props.align || 'center'}
+          imageAlign={props.imageAlign || 'center'}
+          contents={props.children}
+          layout={props.layout}
+        />
+      </Container>
+    )
+
+    const FeatureCallout = () => (
+      <Container className="" background={'light'} padding={['top', 'bottom']}>
+        <div style={{ textAlign: 'center' }}>
+          <p>
+            <i>
+              The more your tests resemble the way your software is used, <br />
+              the more confidence they can give you.
+            </i>
+          </p>
+          <MarkdownBlock>
+            `npm install --save-dev pptr-testing-library`
+          </MarkdownBlock>
+        </div>
+      </Container>
+    )
+
+    const Features = () => (
+      <React.Fragment>
+        <Block layout="threeColumn">
+          {[
+            {
+              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',
+            },
+          ]}
+        </Block>
+      </React.Fragment>
+    )
+
+    return (
+      <div>
+        <HomeSplash siteConfig={siteConfig} language={language} />
+        <div className="mainContainer">
+          <FeatureCallout />
+          <Features />
+        </div>
+      </div>
+    )
+  }
+}
+
+module.exports = Index
diff --git a/website/static/img/puppeteer-275x275.png b/website/static/img/puppeteer-275x275.png
