docs(preact): release initial docs (testing-library#273)

* docs(preact): add logo + link to homepage * docs(preact): release initial docs

Author: mihar-22

docs/preact-testing-library/api.md

@@ -0,0 +1,158 @@
+---
+id: api
+title: API
+sidebar_label: API
+---
+
+- [`@testing-library/dom`](#testing-library-dom)
+- [`render`](#render)
+- [`cleanup`](#cleanup)
+- [`act`](#act)
+- [`fireEvent`](#fireevent)
+
+---
+
+## `@testing-library/dom`
+
+This library re-exports everything from the DOM Testing Library
+(`@testing-library/dom`). See the
+[documentation](../dom-testing-library/api-queries.md) to see what goodies you
+can use.
+
+## `render`
+
+```jsx
+import { render } from '@testing-library/preact'
+
+const { results } = render(<YourComponent />, { options })
+```
+
+### Options
+
+| Option | Description | Default |
+| ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- |
+| `container` | The HTML element the component is mounted to. | baseElement |
+| `baseElement` | The root HTML element to which the container is appended to. | document.body |
+| `queries` | Queries to bind to the baseElement. See [getQueriesForElement](../dom-testing-library/api-helpers#within-and-getqueriesforelement-apis). | null |
+| `hydrate` | Used when the component has already been mounted and requires a rerender. Not needed for most people. The rerender function passed back to you does this already. | false |
+| `wrapper` | A parent component to wrap YourComponent. | null |
+
+### Results
+
+| Result | Description |
+| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `container` | The HTML element the component is mounted to. |
+| `baseElement` | The root HTML element to which the container is appended to. |
+| `debug` | Logs the baseElement using [prettyDom](https://testing-library.com/docs/dom-testing-library/api-helpers#prettydom). |
+| `unmount` | Unmounts the component from the container. |
+| `rerender` | Calls render again passing in the original arguments and sets hydrate to true. |
+| `asFragment` | Returns the innerHTML of the container. |
+| `...queries` | Returns all [query functions](https://testing-library.com/docs/dom-testing-library/api-queries) to be used on the baseElement. If you pass in `query` arguments than this will be those, otherwise all. |
+
+## `cleanup`
+
+Unmounts the component from the container and destroys the container.
+
+📝 When you import anything from the library, this automatically runs after each
+test. If you'd like to disable this then set `process.env.PTL_SKIP_AUTO_CLEANUP`
+to true when running your tests.
+
+```jsx
+import { render, cleanup } from '@testing-library/preact'
+
+afterEach(() => {
+ cleanup()
+}) // Default on import: runs it after each test.
+
+render(<YourComponent />)
+
+cleanup() // Or like this for more control.
+```
+
+## `act`
+
+Just a convenience export that points to preact/test-utils/act. All renders and
+events being fired are wrapped in `act`, so you don't really need this. It's
+responsible for flushing all effects and rerenders after invoking it.
+
+📝 If you'd love to learn more, checkout
+[this explanation](https://github.com/threepointone/react-act-examples/blob/master/sync.md).
+Even thought it's for React, it gives you an idea of why it's needed.
+
+## `fireEvent`
+
+Passes it to the @testing-library/dom
+[fireEvent](../dom-testing-library/api-events). It's also wrapped in `act` so
+you don't need to worry about doing it.
+
+📝 Keep in mind mainly when using `h / Preact.createElement` that React uses a
+Synthetic event system, and Preact uses the browser's native `addEventListener`
+for event handling. This means events like `onChange` and `onDoubleClick` in
+React, are `onInput` and `onDblClick` in Preact. The double click example will
+give you an idea of how to test using those functions.
+
+### Example 1
+
+```jsx
+const cb = jest.fn();
+
+function Counter() {
+ useEffect(cb);
+
+ const [count, setCount] = useState(0);
+
+ return <button onClick={() => setCount(count + 1)}>{count}</button>;
+}
+
+const { container: { firstChild: buttonNode }, } = render(<Counter />);
+
+// Clear the first call to useEffect that the initial render triggers.
+cb.mockClear();
+
+// Fire event Option 1.
+fireEvent.click(buttonNode);
+
+// Fire event Option 2.
+fireEvent(
+button,
+new Event('MouseEvent', {
+ bubbles: true,
+ cancelable: true,
+ button: 0,
+});
+
+expect(buttonNode).toHaveTextContent('1');
+expect(cb).toHaveBeenCalledTimes(1);
+```
+
+### Example 2
+
+```jsx
+const handler = jest.fn()
+
+const {
+ container: { firstChild: input },
+} = render(<input type="text" onInput={handler} />)
+
+fireEvent.input(input, { target: { value: 'a' } })
+
+expect(handler).toHaveBeenCalledTimes(1)
+```
+
+### Example 3
+
+```jsx
+const ref = createRef()
+const spy = jest.fn()
+
+render(
+ h(elementType, {
+ onDblClick: spy,
+ ref,
+ })
+)
+
+fireEvent['onDblClick'](ref.current)
+
+expect(spy).toHaveBeenCalledTimes(1)
+```

docs/preact-testing-library/example.md

@@ -0,0 +1,60 @@
+---
+id: example
+title: Example
+sidebar_label: Example
+---
+
+> Preact Testing Library works with both Preact Hooks and Classes. Your tests
+> will be the same however you write your components.
+
+## Component
+
+```jsx
+function HiddenMessage({ children }) {
+ const [showMessage, setShowMessage] = useState(false)
+
+ return (
+ <div>
+ <label htmlFor="toggle">Show Message</label>
+ <input
+ id="toggle"
+ type="checkbox"
+ onChange={e => setShowMessage(e.target.checked)}
+ checked={showMessage}
+ />
+ {showMessage ? children : null}
+ </div>
+ )
+}
+```
+
+## Test
+
+```jsx
+// NOTE: jest-dom adds handy assertions to Jest and it is recommended, but not required.
+import '@testing-library/jest-dom/extend-expect'
+
+import { h } from 'preact'
+import { render, fireEvent } from '@testing-library/preact'
+
+import HiddenMessage from '../hidden-message'
+
+test('shows the children when the checkbox is checked', () => {
+ const testMessage = 'Test Message'
+
+ const { queryByText, getByLabelText, getByText } = render(
+ <HiddenMessage>{testMessage}</HiddenMessage>
+ )
+
+ // query* functions will return the element or null if it cannot be found.
+ // get* functions will return the element or throw an error if it cannot be found.
+ expect(queryByText(testMessage)).toBeNull()
+
+ // The queries can accept a regex to make your selectors more resilient to content tweaks and changes.
+ fireEvent.click(getByLabelText(/show/i))
+
+ // .toBeInTheDocument() is an assertion that comes from jest-dom.
+ // Otherwise you could use .toBeDefined().
+ expect(getByText(testMessage)).toBeInTheDocument()
+})
+```

docs/preact-testing-library/intro.md

@@ -0,0 +1,46 @@
+---
+id: intro
+title: Intro
+sidebar_label: Introduction
+---
+
+[Preact Testing Library on GitHub][gh]
+
+[gh]: https://github.com/testing-library/preact-testing-library
+
+```
+npm install --save-dev @testing-library/preact
+```
+
+> This library is built on top of
+> [`DOM Testing Library`](dom-testing-library/intro.md) which is where most of
+> the logic behind the queries is.
+
+## The Problem
+
+You want to write tests for your Preact components so that they avoid including
+implementation details, and are maintainable in the long run.
+
+## This Solution
+
+The Preact Testing Library is a very lightweight solution for testing Preact
+components. It provides light utility functions on top of `preact/test-utils`,
+in a way that encourages better testing practices. Its primary guiding principle
+is:
+
+> [The more your tests resemble the way your software is used, the more confidence they can give you.](https://twitter.com/kentcdodds/status/977018512689455106)
+
+See the [Dom introduction][dom-solution-explainer] and [React
+introduction][react-solution-explainer] for a more in-depth explanation.
+
+[dom-solution-explainer]: ../dom-testing-library/intro.md#this-solution
+[react-solution-explainer]: ../react-testing-library/intro#this-solution
+
+**What this library is not**:
+
+1. A test runner or framework.
+2. Specific to a testing framework.
+
+We recommend Jest as our preference. You can checkout
+[Using Without Jest](../react-testing-library/setup#using-without-jest) if
+you're looking to use another framework.

docs/preact-testing-library/learn.md

@@ -0,0 +1,32 @@
+---
+id: learn
+title: Learn
+sidebar_label: Learn
+---
+
+Due to the similarities between React and Preact (including the testing
+libraries), you should be able to comfortably use any React based examples,
+docs, answers on stack overflow etc.
+
+Take note of the
+[differences between React and Preact](https://preactjs.com/guide/v10/differences-to-react).
+
+If you're still hungry for more at this point than checkout:
+
+- The dom-testing-library:
+ - [Introduction](../intro.md)
+ - [Queries](../dom-testing-library/api-queries)
+ - [Firing Events](../dom-testing-library/api-events)
+ - [Async Utilities](../dom-testing-library/api-async.md)
+ - [Helpers](../dom-testing-library/api-helpers)
+ - [FAQ](../dom-testing-library/faq.md)
+- The react-testing-library:
+ - [API](../react-testing-library/api.md)
+ - [Example](../react-testing-library/example-intro.md)
+ - [Sandbox](https://codesandbox.io/s/github/kentcdodds/react-testing-library-examples)
+ - [FAQ](../react-testing-library/faq.md)
+- This YouTube video by LevelUpTuts called
+ [What is React Testing Library?](https://youtu.be/JKOwJUM4_RM)
+- Extending Jest with
+ [custom matchers](https://github.com/testing-library/jest-dom) to test the
+ state of the DOM.

website/pages/en/index.js

@@ -235,6 +235,12 @@ class Index extends React.Component {
  title:
  '[Native Testing Library](./docs/native-testing-library/intro)',
  },
+ {
+ image: `${baseUrl}img/preact-128x128.png`,
+ imageAlign: 'top',
+ title:
+ '[Preact Testing Library](./docs/preact-testing-library/intro)',
+ },
  {
  image: `${baseUrl}img/construction-128x128.png`,
  imageAlign: 'top',

website/sidebars.json

@@ -80,6 +80,16 @@
  "angular-testing-library/api"
  ]
  },
+ {
+ "type": "subcategory",
+ "label": "Preact Testing Library",
+ "ids": [
+ "preact-testing-library/intro",
+ "preact-testing-library/example",
+ "preact-testing-library/api",
+ "preact-testing-library/learn"
+ ]
+ },
  "cypress-testing-library/intro",
  "svelte-testing-library/intro",
  "pptr-testing-library/intro",