add testing guidelines

webapp/README.md

@@ -38,7 +38,7 @@ $ yarn start
 We ensure the quality of our frontend code by using
 - [ESLint](https://eslint.org/) for checking our JavaScript code
 - [Jest](https://jestjs.io/) and [Vue Test Utils](https://vue-test-utils.vuejs.org/) to unit test our components
-- [Storybook](https://storybook.js.org/) to manually test our components in an isolated playground
+- [Storybook](https://storybook.js.org/) to document and manually test our components in an isolated playground
 
 For more information see our [frontend testing guide](testing.md). Use these commands to run the tests:
 

webapp/html.md

@@ -20,3 +20,10 @@ HTML is used to _structure content on the page_ and should therefore reflect its
 Why?
 - deep nesting makes it hard to understand, style and maintain components
 - it can lead to performance issues
+
+## Recommended reads
+
+For a deeper dive into the WHY and HOW have a look at the following resources:
+
+- [HTML: a good basis for accessibility](https://developer.mozilla.org/en-US/docs/Learn/Accessibility/HTML)
+- [Why, how, and when to use semantic HTML and ARIA](https://css-tricks.com/why-how-and-when-to-use-semantic-html-and-aria/)

webapp/storybook.md

@@ -1,33 +0,0 @@
-### Storybook
-
-We encourage contributors to use Storybook to test out new components in an isolated way, and benefit from its many features.
-See the docs for live examples and answers to FAQ, among other helpful information. ![Storybook docs](https://storybook.js.org/docs/basics/introduction/)
-
-{% tabs %}
-{% tab title="Docker" %}
-
-After you have started the application following the instructions above, in another terminal run:
-
-```bash
-$ docker-compose exec webapp yarn storybook
-```
-The output should look similar to this:
-
-![Storybook output](../.gitbook/assets/storybook-output.png)
-
-Click on the link http://localhost:3002/ to open the browser to your interactive storybook.
-
-{% endtab %}
-
-{% tab title="Without Docker" %}
-Run the following command:
-
-```bash
-# in webapp/
-yarn storybook
-```
-
-Open http://localhost:3002/ in your browser
-
-{% endtab %}
-{% endtabs %}

webapp/testing.md

@@ -1,8 +1,31 @@
 # Component Testing
 
-We are using `Jest` as our test runner, along with `vue-test-utils`.
+## Linting
 
-Head over and check out the documentation on [Jest](https://jestjs.io/docs/en/getting-started.html)
+We use [ESLint](https://eslint.org/) to make sure all developers follow certain code guidelines when writing JavaScript.
 
-Also, check out [vue-test-utils](https://vue-test-utils.vuejs.org/)
+Most code editors offer an ESLint plugin which helps detect mistakes already while you are writing code. To run the linter manually before pushing up new code type `yarn lint` into your terminal. Most minor issues can be fixed automatically with the command `yarn lint --fix`.
 
+## Unit tests
+
+We write unit tests with the help of [Jest](https://jestjs.io/) and [Vue Test Utils](https://vue-test-utils.vuejs.org/) to make sure our components work in the way they should. In these tests we usually check that a certain input leads to the expected output. They are used to test _functionality_.
+
+To run all tests use the command `yarn test` in the `/webapp` directory. Other useful commands are:
+- `yarn test -t test-name` to run tests including `test-name` in their file or test names
+- `yarn test -o` to run tests related to files that have been changed since the latest commit
+
+## Documentation and manual testing
+
+[Storybook](https://vue-test-utils.vuejs.org/) is a great tool that performs two important functions in our project:
+
+### Component documentation
+
+With Storybook our components can be documented in detail and offer a visual reference to other developers. When all components are properly documented Storybook can be used as a big component library – where developers can browse through design tokens and components and immediately verify that the component offers the desired functionality.
+
+### Manual testing in an isolated environment
+
+When adding new components or changing existing ones Storybook can be helpful not only to document the feature for future use but also to test different use cases (e.g. by passing different types of `props`) in an isolated playground.
+
+With the right addons Storybook also gives immediate feedback on how well the component complies with accessibility guidelines.
+
+To run Storybook first start the app, then enter the following command in a new terminal window: `yarn storybook`. The Human Connection Storybook will then be available on `http://localhost:3002`.