From 068a633716ff02663fbe81efdc9e702b788d5bc4 Mon Sep 17 00:00:00 2001
From: Dennis Eichhorn <spl1nes.com@googlemail.com>
Date: Sat, 21 Nov 2020 23:58:01 +0100
Subject: [PATCH] improve docs

---
 SUMMARY.md                 |  2 +-
 quality/inspections.md     | 29 +++++++++++++++++++++++++++--
 standards/documentation.md | 26 ++++++++++++++++++++++++--
 3 files changed, 52 insertions(+), 5 deletions(-)

diff --git a/SUMMARY.md b/SUMMARY.md
index d5f23f1..9b36334 100644
--- a/SUMMARY.md
+++ b/SUMMARY.md
@@ -4,7 +4,7 @@
 * [Application Structure]({%}&page=general/structure)
 
 ## Quality & Standards
-* [Code Inspection]({%}&page=quality/inspections)
+* [Code Inspections & Tests]({%}&page=quality/inspections)
 * [Documentation Standards]({%}&page=standards/documentation)
 * [General Code Standards]({%}&page=standards/general)
 * [Security Standards]({%}&page=security/security_guidelines)
diff --git a/quality/inspections.md b/quality/inspections.md
index 31e252e..d2feed9 100644
--- a/quality/inspections.md
+++ b/quality/inspections.md
@@ -14,18 +14,43 @@ The following testing requirements must be met:
 * no usage of deprecated function calls
 * no code style violations
 * every test should have a short description for the test report
+* every file containing code (except enums, traits, interfaces and template files) must have their own test file with tests
+
+When testing it makes sense to test for the happy path/branch of how a method should work and to `try` and break things by trying to find inputs and paths which may lead to unexpected behavior and errors.
 
 ### Unit tests
 
-Every test must be in it's own test function.
-Every public function must have a unit test
+The smallest/lowest level of testing are the unit tests. Unit tests should be implemented for models and framework methods. Every public function should be covered by at least one unit test. If a method has multiple branches every branch should be covered by a separate unit test. In some cases it might make sense to cover multiple branches in one unit test/test function, such a decision should however be made conciously.
 
 ### Integration tests
 
+Integration tests are the second level or middle level of tests. These types of tests are used for example for module controllers. In such tests you should mock a request and test the response.
+
+For large controllers it can make sense to define a `*ControllerTest` which uses `Traits` in order to categorize different suits of tests. For example in the `Admin` ApiControllerTest we implemented different traits for group, account and module tests.
+
 ### System tests
 
+The system tests are the highest level of tests and test the overall functionality and if the implementation fulfills the specifications.
+
+### Modules
+
+Every module must implement the following tests if applicable:
+
+* general module tests (e.g. install, update, delete, status change)
+* admin tests (`use \Modules\tests\ModuleTestTrait;`)
+* model tests (unit tests)
+* controller tests (e.g. ApiController tests)
+* view tests
+
+You can find an example in the TestModule.
+
 ## Test documentation
 
+* every test must have a short test description
+* every test and description must be added to the test report
+* every test needs a test category (e.g. framework, module etc.)
+* every test should have a @covers annotation to specify which class it covers
+
 ## Tools
 
 Tools used for the code inspection are:
diff --git a/standards/documentation.md b/standards/documentation.md
index 11b4466..5fbc107 100644
--- a/standards/documentation.md
+++ b/standards/documentation.md
@@ -1,13 +1,35 @@
 # Documentation
 
-## User
+## Module
 
-## Developer
+Every module must have two types of documentation. One for the end-user, which also includes information for the administrator and module configuration and another documentation for developers. Documentation must be available in at least english language.
+
+### User
+
+The user documentation should cover the following aspects:
+
+* Installation, update, status change and delete process
+* Dependencies and requirements
+* Configuration options
+* Permission management
+* How to use the module and its functionality from an end-user perspective
+
+### Developer
+
+The developer documentation should cover the following aspects:
+
+* Database UML diagram (incl. relations to other modules)
+* How to interact with the controllers, views and models from other modules
+* How to interact with the controllers, views and models from within the module
+* Best practices (does and don'ts)
+* Module specific guidelines & contribution information
 
 ## Database
 
 ### Diagramms
 
+Every module that has a database table must implement a UML diagram illustrating the internal table relations as well as the relations with external tables from other modules.
+
 ## Php
 
 The php documentation is based on PhpDocumentor, therefore only valid PhpDocumentor comments are valid for files, classes, functions/methods and (member) variables.