Add Docs about Cypress, react-testing-library and testing of CSS-in-JS (#6708)

* Add Docs about Cypress, react-testing-library and testing of CSS-in-JS

* Small fixes

* Update link

* Minor edits

* Change titles

* Edits

* Address Shannon's comments

Author: LekoArts

docs/docs/end-to-end-testing.md

@@ -0,0 +1,50 @@
+---
+title: "End-to-end testing"
+---
+
+[Cypress](https://www.cypress.io/) is one of the options when it comes to end-to-end (E2E) testing. Cypress is a all-in-one testing framework focused on E2E testing meaning that you don't have to install 10 different things to get your test suite set up. You can write your first passing test in minutes without any configuration with the help of Cypress' API which is easy to read and understand. It runs tests as fast as your browser can render content which also makes test-driven development possible. You'll also profit from the time travel feature or the extensive debugging capabilities with Chrome DevTools. Of course you can also use it with Gatsby and this guide will explain how.
+
+In order to run Gatsby's development server and Cypress at the same time you'll use the little helper [start-server-and-test](https://github.com/bahmutov/start-server-and-test). If you're already using [react-testing-library](docs/testing-react-components) for [unit testing](docs/unit-testing) you might want to install [cypress-testing-library](https://github.com/kentcdodds/cypress-testing-library), too. This way you can use the exact same methods you used with `react-testing-library` in your Cypress tests. Install the following packages to your `devDependencies`:
+
+```sh
+npm install --save-dev cypress start-server-and-test
+```
+
+We also want the urls used by `cy.visit()` or `cy.request()` to be prefixed hence you have to create the file `cypress.json` at the root of your project with the following content:
+
+```json
+{
+  "baseUrl": "http://localhost:8000/"
+}
+```
+
+Last but not least you add additional scripts to your `package.json` to run Cypress:
+
+```json
+{
+  "scripts": {
+    "develop": "gatsby develop",
+    "cy:open": "cypress open",
+    "test:e2e": "start-server-and-test develop http://localhost:8000 cy:open"
+  }
+}
+```
+
+Run `test:e2e` in your command line and see Cypress running for the first time. A folder named `cypress` will be created at the root of your project and a new application window will pop up. [Cypress' getting started guide](https://docs.cypress.io/guides/getting-started/writing-your-first-test.html#) is a good start to learn how to write tests!
+
+### Continuous Integration
+
+If you want to run Cypress in Continuous Integration (CI) you have to use `cypress run` instead of `cypress open`:
+
+```json
+{
+  "scripts": {
+    "develop": "gatsby develop",
+    "cy:open": "cypress open",
+    "cy:run": "cypress run",
+    "test:e2e:ci": "start-server-and-test develop http://localhost:8000 cy:run"
+  }
+}
+```
+
+Please read the [Cypress' official documentation](https://docs.cypress.io/guides/guides/continuous-integration.html) on CI if you want to know how to setup Travis or Gitlab with Cypress.

docs/docs/testing-css-in-js.md

@@ -0,0 +1,144 @@
+---
+title: "Testing CSS-in-JS"
+---
+
+Popular CSS-in-JS libraries like [styled-components](https://github.com/styled-components/styled-components) or [emotion](https://github.com/emotion-js/emotion) can also be tested with the help of [jest-styled-components](https://github.com/styled-components/jest-styled-components) or [jest-emotion](https://github.com/emotion-js/emotion/tree/master/packages/jest-emotion) respectively. These packages improve Jest's built-in snapshot testing experience and are a great way to help avoid unintended changes to your website's UI. Please refer to your package's documentation to see if it also offers testing capabilities.
+
+*Snapshot serializers* like `jest-styled-components` or `jest-emotion` modify the standard output to a more meaningful and readable snapshot, e.g. by removing unnecessary information or displaying data in another format. Which ultimately leads to more compareable and effective snapshot tests.
+
+By default snapshots of your styled components show the generated class names (which you didn't set) and no styling information. When changing the styles you'll only see the diff of some cryptic class names (hashes). That's why you should use the above mentioned *snapshot serializers*. They remove the hashes and format the CSS in style elements.
+
+For this example we'll use emotion. The testing utilities of emotion and glamor are largely based on [jest-styled-components](https://github.com/styled-components/jest-styled-components) so they have a similar usage. Please have a look at the testing section of your library to follow along.
+
+## Installation
+
+```sh
+npm install --save-dev jest-emotion babel-plugin-emotion
+```
+
+As [Gatsby's emotion plugin](https://www.gatsbyjs.org/packages/gatsby-plugin-emotion/) is using `babel-plugin-emotion` under the hood you'll also need to install it so that Jest can use it.
+
+If you followed along with the [Unit testing guide](docs/unit-testing) you'll have the file `jest-preprocess.js` at the root of your project. Open that file and add the plugin:
+
+```diff
+const babelOptions = {
+  presets: ["@babel/react", "@babel/env"],
+  plugins: [
++    "emotion",
+    "@babel/plugin-proposal-optional-chaining",
+    "@babel/plugin-proposal-class-properties",
+  ],
+}
+
+module.exports = require("babel-jest").createTransformer(babelOptions)
+```
+
+In order to tell Jest to use the serializer you'll need to create the file `setup-test-env.js` which will be run automatically before every test. Create the file `setup-test-env.js` at the root of your project. Insert this code into it:
+
+```js
+import { createSerializer } from 'jest-emotion';
+import * as emotion from 'emotion';
+
+expect.addSnapshotSerializer(createSerializer(emotion));
+```
+
+Lastly you need to tell Jest where to find this file. Open your `package.json` and add this entry to your `"jest"` section:
+
+```json
+"jest": {
+  "setupTestFrameworkScriptFile": "<rootDir>/setup-test-env.js"
+}
+```
+
+## Usage
+
+In this example you'll use `react-test-renderer` but you can also use [react-testing-library](docs/testing-react-components) or any other appropriate library. Because you created the `setup-test-env.js` file you can write your unit tests like you used to do. But now you'll also get the styling information!
+
+```js
+// src/components/Button.test.js
+
+import React from 'react'
+import styled from 'react-emotion'
+import renderer from 'react-test-renderer'
+
+const Button = styled.div`
+  color: hotpink;
+`
+
+test('Button renders correctly', () => {
+  expect(
+    renderer.create(<Button>This is hotpink.</Button>).toJSON()
+  ).toMatchSnapshot()
+})
+```
+
+The resulting snapshot will look like this:
+
+```js
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`Button renders correctly 1`] = `
+.emotion-0 {
+  color: hotpink;
+}
+
+<div
+  className="emotion-0 emotion-1"
+>
+  This is hotpink.
+</div>
+`;
+```
+
+If your styled component depends on `theme` via `ThemeProvider` you'll have two options:
+
+- Wrap all your components with the `ThemeProvider`
+- Use API helpers (have a look at the library's documentation, e.g. [styled-components](https://github.com/styled-components/jest-styled-components#theming) or [emotion](https://github.com/emotion-js/emotion/tree/master/packages/emotion-theming#createbroadcast-function))
+
+And this is where snapshots tests really shine. If you change, e.g. the primary color in your theme file you'll see which components get affected by this change. This way you can catch unintended changes to the style of your components.
+
+This example uses the first option:
+
+```js
+// src/components/Wrapper.test.js
+
+import React from 'react'
+import { ThemeProvider } from 'emotion-theming'
+import renderer from 'react-test-renderer'
+
+const theme = {
+  maxWidth: '1450px',
+}
+
+const Wrapper = styled.section`
+  max-width: ${props => props.theme.maxWidth};
+`
+
+test('Wrapper renders correctly', () => {
+  expect(
+    renderer.create(
+      <ThemeProvider theme={theme}>
+        <Wrapper>Content.</Wrapper>
+      </ThemeProvider>
+    ).toJSON()
+  ).toMatchSnapshot()
+})
+```
+
+The resulting snapshot will look like this:
+
+```js
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`Wrapper renders correctly 1`] = `
+.emotion-0 {
+  max-width: 1450px;
+}
+
+<section
+  className="emotion-0 emotion-1"
+>
+  Content
+</div>
+`;
+```

docs/docs/testing-react-components.md

@@ -0,0 +1,57 @@
+---
+title: "Testing React components"
+---
+
+_The recommended testing framework is [Jest](https://jestjs.io/). This guide assumes that you followed the [Unit testing](docs/unit-testing) guide to setup Jest._
+
+Kent C. Dodds' [react-testing-library](https://github.com/kentcdodds/react-testing-library) has risen in popularity since its release and is a great replacement for [enzyme](https://github.com/airbnb/enzyme). You can write unit and integration tests and it encourages you to query the DOM in the same way the user would. Hence the guiding principle:
+
+> The more your tests resemble the way your software is used, the more confidence they can give you.
+
+It provides light utility functions on top of `react-dom` and `react-dom/test-utils` and gives you the confidence that refactors of your component in regards to the implementation (but not functionality) don't break your tests.
+
+## Installation
+
+Install the library as one of your project's `devDependencies`. Optionally you may install `jest-dom` to use its [custom jest matchers](https://github.com/gnapse/jest-dom#custom-matchers).
+
+```sh
+npm install --save-dev react-testing-library jest-dom
+```
+
+Create the file `setup-test-env.js` at the root of your project. Insert this code into it:
+
+```js
+import 'jest-dom/extend-expect';
+
+// this is basically: afterEach(cleanup)
+import 'react-testing-library/cleanup-after-each';
+```
+
+This file gets run automatically by Jest before every test and therefore you don't need to add the imports to every single test file.
+
+Lastly you need to tell Jest where to find this file. Open your `package.json` and add this entry to your `"jest"` section:
+
+```json
+"jest": {
+  "setupTestFrameworkScriptFile": "<rootDir>/setup-test-env.js"
+}
+```
+
+## Usage
+
+Let's create a little example test using the newly added library. If you haven't done already read the [unit testing guide](docs/unit-testing) — essentially you'll use `react-testing-library` instead of `react-test-renderer` now. There are a lot of options when it comes to selectors, this example chooses `getByTestId` here. It also utilizes `toHaveTextContent` from `jest-dom`:
+
+```js
+import React from 'react'
+import { render } from 'react-testing-library'
+
+// You have to write data-testid
+const Title = () => <h1 data-testid="hero-title">Gatsby is awesome!</h1>
+
+test('Displays the correct title', () => {
+  const { getByTestId } = render(<Title />)
+  // Assertion
+  expect(getByTestId('hero-title')).toHaveTextContent('Gatsby is awesome!')
+  // --> Test will pass
+})
+```