Improve existing documentation

Improve documentation for different markdown documentation files. Goal
is to simplify and make the language and content more clear.

docs/tests.md

@@ -1,23 +1,28 @@
 # Tests
 
-- There are two different types of tests executed:
-  1. [Unit tests](#unit-tests)
-  2. [Integration tests](#integration-tests)
-  3. [End-to-end (E2E) tests](#e2e-tests)
-- All tests
-  - Uses [Mocha](https://mochajs.org/) and [Chai](https://www.chaijs.com/).
-  - Are written in files that includes `.spec` extension.
-- 💡 You can use path/module alias `@/tests` in import statements.
+There are different types of tests executed:
+
+1. [Unit tests](#unit-tests)
+2. [Integration tests](#integration-tests)
+3. [End-to-end (E2E) tests](#e2e-tests)
+
+Common aspects for all tests:
+
+- They use [Mocha](https://mochajs.org/) and [Chai](https://www.chaijs.com/).
+- Their files end with `.spec.{ts|js}` suffix.
+
+💡 You can use path/module alias `@/tests` in import statements.
 
 ## Unit tests
 
-- Tests each component in isolation.
-- Defined in [`./tests/unit`](./../tests/unit).
+- Unit tests test each component in isolation.
+- All unit tests goes under [`./tests/unit`](./../tests/unit).
+- They rely on [stubs](./../tests/unit/shared/Stubs) for isolation.
 
 ### Unit tests structure
 
 - [`./src/`](./../src/)
-  - Includes code that will be tested tested.
+  - Includes source code that unit tests will test.
 - [`./tests/unit/`](./../tests/unit/)
   - Includes test code.
   - Tests follow same folder structure as [`./src/`](./../src).
@@ -29,7 +34,7 @@
       - Asserting functions should start with `expect` prefix.
     - [`TestCases/`](./../tests/unit/shared/TestCases/)
       - Shared test cases.
-      - Test runner functions that uses `it()` from Mocha test [Mocha test framework](https://mochajs.org/) should be prefixed with `it.`
+      - Functions that calls `it()` from [Mocha test framework](https://mochajs.org/) should have `it` prefix.
         - E.g. `itEachAbsentCollectionValue()`.
     - [`Stubs/`](./../tests/unit/shared/Stubs)
       - Includes stubs to be able to test components in isolation.
@@ -38,39 +43,39 @@
 ### Unit tests naming
 
 - Each test suite first describe the system under test.
-  - E.g. tests for class `Application` is categorized under `Application`.
-- Tests for specific methods are categorized under method name (if applicable).
-  - E.g. test for `run()` is categorized under `run`.
+  - E.g. tests for class `Application.ts` are all inside `Application.spec.ts`.
+- `describe` blocks tests for same function (if applicable).
+  - E.g. test for `run()` are inside `describe('run', () => ..)`.
 
 ### Act, arrange, assert
 
 - Tests use act, arrange and assert (AAA) pattern when applicable.
 - **Arrange**
-  - Should set up the test case.
+  - Sets up the test case.
   - Starts with comment line `// arrange`.
 - **Act**
-  - Should cover the main thing to be tested.
+  - Executes the actual test.
   - Starts with comment line `// act`.
 - **Assert**
-  - Should elicit some sort of response.
+  - Elicit some sort of expectation.
   - Starts with comment line `// assert`.
 
 ## Integration tests
 
 - Tests functionality of a component in combination with others (not isolated).
 - Ensure dependencies to third parties work as expected.
-- Defined in [`./tests/integration`](./../tests/integration).
+- Defined in [./tests/integration](./../tests/integration).
 
 ## E2E tests
 
 - Test the functionality and performance of a running application.
-- E2E tests are configured by vue plugin [`e2e-cypress`](https://github.com/vuejs/vue-cli/tree/dev/packages/@vue/cli-plugin-e2e-cypress#readme) for Vue CLI.
-- Names and folders are structured logically based on tests.
+- Vue CLI plugin  [`e2e-cypress`](https://github.com/vuejs/vue-cli/tree/dev/packages/@vue/cli-plugin-e2e-cypress#readme) configures E2E tests.
+- Test names and folders have logical structure based on tests executed.
 - The structure is following:
   - [`cypress.json`](./../cypress.json): Cypress configuration file.
   - [`./tests/e2e/`](./../tests/e2e/): Base Cypress folder.
-    - [`/specs/`](./../tests/e2e/specs/): Test files, test are named with `.spec.js` extension.
-    - [`/plugins/index.js`](./../tests/e2e/plugins/index.js): Plugin file executed before project is loaded.
+    - [`/specs/`](./../tests/e2e/specs/): Test files named with `.spec.js` extension.
+    - [`/plugins/index.js`](./../tests/e2e/plugins/index.js): Plugin file executed before loading project.
     - [`/support/index.js`](./../tests/e2e/support/index.js): Support file, runs before every single spec file.
     - *(Ignored)* `/videos`: Asset folder for videos taken during tests.
     - *(Ignored)* `/screenshots`: Asset folder for Screenshots taken during tests.