docs(screener-io): added documentation on how to write tests with steps (#856)

* draft change for the docs

* added doctoc generated links

* added changelog

* fixed a comment

* a few improvements in the docs

Author: silviuaavram

.github/test-a-feature.md

@@ -11,6 +11,12 @@ Test a feature
   - [isConformant (required)](#isconformant-required)
   - [Writing tests](#writing-tests)
   - [Running tests](#running-tests)
+- [Screener Tests](#screener-tests)
+  - [Tests with Steps API](#tests-with-steps-api)
+    - [Example for a test file:](#example-for-a-test-file)
+    - [Important mentions:](#important-mentions)
+  - [Run Screener tests](#run-screener-tests)
+    - [Local run command](#local-run-command)
 
 <!-- END doctoc generated TOC please keep comment here to allow auto update -->
 
@@ -103,4 +109,49 @@ yarn test
 yarn test:watch
 ```
 
-[1]: https://github.com/stardust-ui/react/tree/master/test/specs/commonTests
+[1]: https://github.com/stardust-ui/react/tree/master/test/specs/commonTests
+
+## Screener Tests
+
+For some components, it is necessary to write screenshot tests in order to check that they render properly. For each component example added to the docsite a screenshot test is automatically created. This checks if that the component is rendered in a consistent way, as it looks for visual differences between the previous rendering and the current one. We use [screener-io](https://screener.io/) to achieve screenshot testing.
+
+### Tests with Steps API
+
+This default test only checks the rendering for the component in its initial state. In order to test the rendering of more complex components, such as a `Dropdown`, screener provides an [api](https://www.npmjs.com/package/screener-runner) to execute actions on the DOM, in a way similar to end-to-end tests. These tests are executed by Screener as long as both the tests and their files respect the conventions:
+- the test file should be placed at the same location as the component example under test.
+- the test file should be named exactly as the component example file. If `DropdownExample.shorthand.tsx` is to be tested, the screener test file should be named `DropdownExample.shorthand.steps.ts`.
+- the tests should be written as an array of callbacks that accept a `steps` parameter, as all of them will be chained in `screener.config`. The `steps` parameter is actually the `Steps` object from screener, instantiated in `screener.config`.
+
+#### Example for a test file:
+
+```tsx
+import { Dropdown } from '@stardust-ui/react'
+
+const steps = [
+  steps => steps.click(`.${Dropdown.slotClassNames.triggerButton}`)
+    .snapshot('Opens dropdown list'),
+  steps => steps.hover(`.${Dropdown.slotClassNames.itemsList} li:nth-child(2)`)
+    .snapshot('Highlights an item'),
+]
+
+export default steps
+```
+
+#### Important mentions:
+
+- by convention, each test is written as a different callback and added to the steps array.
+- an actual assertion is performed by taking a `.snapshot(<Your test name here>)`, as the assertion is performed by comparing the screenshot with the one taken on the previous run and considered correct.
+- a test can have as many snapshots as needed.
+- before the snapshot is taken, steps are added to reach the state of assertion, with methods from `screener-runner` API (`.click(<selector>)`, `.hover(<selector>)`etc.)
+- tests do not perform any cleanup by default. This means a test is dependent on the state of the component in which the previous test leaves it. In the example above, the second test will receive the `Dropdown` component with the list open.
+
+### Run Screener tests
+In order to run the tests locally, make sure to have a Screener API key saved in the environment variables on your machine. For instance, on MacOS/Linux you can use `export SCREENER_API_KEY=<Your screener key here>`.
+
+When ran locally, not all the tests may be needed to run, only the ones added/edited. This can be achieved by changing the regexp in `screener.config.js`, where the `states` property is created. Make sure not to commit that change though! Results can be viewed in the Screener online dashboard, among all the other runs (for master, pull requests, etc.)
+
+#### Local run command
+
+```bash
+yarn test:visual
+```

CHANGELOG.md

@@ -29,6 +29,9 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 ### Fixes
 - Focus the last focused element which triggered `Popup` on ESC @sophieH29 ([#861](https://github.com/stardust-ui/react/pull/861))
 
+### Documentation
+- Add screener with steps testing documentation @silviuavram ([#856](https://github.com/stardust-ui/react/pull/856))
+
 <!--------------------------------[ v0.20.0 ]------------------------------- -->
 ## [v0.20.0](https://github.com/stardust-ui/react/tree/v0.20.0) (2019-02-06)
 [Compare changes](https://github.com/stardust-ui/react/compare/v0.19.2...v0.20.0)