Web docs for tests

ulitol97 · May 1, 2022 · 0102e5f · 0102e5f
1 parent 3a14ea0
commit 0102e5f
Show file tree

Hide file tree

Showing 2 changed files with 49 additions and 33 deletions.
diff --git a/api/src/test/scala/validation/ouputs/SchemaTests.scala b/api/src/test/scala/validation/ouputs/SchemaTests.scala
@@ -31,7 +31,7 @@ import org.scalatest.matchers.should.Matchers
  *       since we should be able to trust SHaclEX as a validation library
  *
  *       Still,
- *       it is unstable and its better to double check the SHaclEX validator in
+ *       it is unstable, and it's better to double-check the SHaclEX validator in
  *       our streaming context
  */
 //noinspection RedundantDefaultArgument

diff --git a/docs/5-testing_auditing/unit-tests.md b/docs/5-testing_auditing/unit-tests.md
@@ -5,50 +5,66 @@ title: Unit tests
 
 # Unit tests
 
-## Command Reference
+@APP_NAME@ comes with some built-in unit tests written with:
 
-@APP_NAME@'s CLI currently supports the following launch-arguments:
+- [scalatest](https://www.scalatest.org/): an extensible, widely adopted scala
+  testing framework.
+- [cats-effect-testing](https://github.com/typelevel/cats-effect-testing):
+  Typelevel's compatibility layer between cats-effect and tests frameworks
 
-- `--https` Attempt to serve the API via HTTPS (default is false), searching for
-  certificates as specified in the current environment.
-- `-p, --port`  Port in which the API will listen for requests. Values must be
-  in range 1-65535 (default is 8080).
-- `-s, --silent`  Enable silent mode in order not to log any output to console (
-  default is false)
-- `-v, --verbose` Show additional logging information (use cumulative times for
-  additional info, like: `-vvv`)
-- `--version` Print the version of the program
-- `--help` Print the help menu
+You may run the tests by running `sbt test` or simply `test` from the SBT shell.
 
-## Verbosity levels
+## Scope
 
-When using the `-v, --verbose` CLI argument, the following logging messages are
-shown on console at each time:
+The provided tests broadly cover the following areas:
 
-- `No verbose argument` **ERROR** level messages
-- `-v` **WARN** level messages and upwards
-- `-vv` **INFO** level messages and upwards (includes client connections and
-  requests)
-- `-vvv` **DEBUG** level messages and upwards
+### Validation tests
 
-## JVM Custom Arguments
+Test the working of the validators in different scenarios.
 
-In case @APP_NAME@ is having trouble to generate permalinks due to an SSL issue,
-try adding the following argument:
+#### Results
 
-- `-Djdk.tls.client.protocols=TLSv1.2`
+- Goals:
+  - Ensure that the underlying RDF validation mechanism works when using either
+    ShEx or SHACL schemas.
+
+> The testing of the validation mechanism could be considered redundant, since we should be able to trust [SHaclEX](https://www.weso.es/shaclex/) as a validation library. However, SHaclEX is unstable, and it's better to double-check the SHaclEX validator in our streaming context.
 
-## Examples
+- Modus operandi:
+  1. RDF data is generated in all accepted formats.
+  2. Validation schemas are generated in all accepted engines and formats.
+  3. All combinations are used to perform validations, testing that the
+     validation output is correct
 
-1. Launching @APP_NAME@ in port 8081:
+#### Halting
 
-- `rdfshape -p 8081`
+- Goals:
+  - Ensure that @APP_NAME@'s validation stream halts when configured to do so
+    for either invalid or erroring validations
 
-2. Launching @APP_NAME@ in port 80, try to use the HTTPS configuration from the
-   environment:
+- Modus operandi: 
+  1. Well formatted and badly formatted RDF data is generated
+  2. Validation schemas that won't validate the data are generated
+  3. The data is validated against the schemas, checking that the correct error
+       is thrown for each situation.
 
-- `rdfshape -p 80 --https`
+#### Timeout
 
-3. Launching @APP_NAME@ in port 8080, with the maximum verbosity level:
+- Goals:
+  - Ensure that @APP_NAME@'s validation stream forcibly halts according to its
+    extractor timeout when no items are received after some time
 
-- `rdfshape -vvv`
+- Modus operandi:
+  1. A trivial validator is run with an unfeasible timeout
+  2. Check that a timeout error is thrown when the validator is initiated
+
+### Extractor tests
+
+- Goals:
+  - Test that the pre-configured extractors work as intended, regardless of the
+    validation results.
+
+- Modus operandi:
+  1. Some trivial but valid RDF/Schema combinations are produced and then
+    consumed by a validator, but each time the validator will be fed through a
+    different extractor to make sure all extractors work the same.