Merge pull request #65 from hug-dev/document-tests

Add documentation of existing tests
parallaxsecond · Sep 21, 2020 · 2e090a4 · 2e090a4
2 parents 23e8872 + d7a7886
commit 2e090a4
Show file tree

Hide file tree

Showing 8 changed files with 73 additions and 13 deletions.
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -7,7 +7,7 @@ jobs:
     name: Build
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v1
+    - uses: actions/checkout@v2
     - name: Install mdbook
       run: cargo install mdbook
     - name: Build book
@@ -17,15 +17,24 @@ jobs:
     name: Check formatting
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v1
+    - uses: actions/checkout@v2
     - name: Create a Go workspace and install vmdfmt
       run: |
           mkdir /tmp/go
           export GOPATH=/tmp/go
           go get github.com/bobertlo/vmd/cmd/vmdfmt
-    - name: Link Checker
-      uses: peter-evans/link-checker@v1
     - name: Check formatting
       run: |
           export PATH="$PATH:/tmp/go/bin:$(pwd)/node_modules/.bin"
           ./ci/check_format.sh
+
+  links:
+    name: Check links
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v2
+    - name: Link Checker
+      id: lc
+      uses: peter-evans/link-checker@v1
+    - name: Fail if there were link errors
+      run: exit ${{ steps.lc.outputs.exit_code }}
diff --git a/README.md b/README.md
@@ -38,7 +38,7 @@ will check if your files are formatted correctly.
 
 ## Contributing
 
-Please check the [**Contribution Guidelines**](https://parallaxsecond.github.io/parsec-book/contributing.html)
+Please check the [**Contribution Guidelines**](https://parallaxsecond.github.io/parsec-book/contributing/index.html)
 to know more about the contribution process.
 
 ## License

diff --git a/src/SUMMARY.md b/src/SUMMARY.md
@@ -57,7 +57,8 @@
    - [How to build and run Parsec](parsec_service/build_run.md)
    - [How to securely install Parsec on Linux](parsec_service/install_parsec_linux.md)
    - [Parsec Configuration](parsec_service/configuration.md)
-   - [How to test Parsec](parsec_service/test.md)
+   - [How to test Parsec](parsec_service/tests/README.md)
+      - [List of existing tests](parsec_service/tests/existing_tests.md)
 - [Contributing](contributing/README.md)
    - [How to add operations to Parsec](contributing/adding_new_operation_how_to.md)
 

diff --git a/src/contributing/adding_new_operation_how_to.md b/src/contributing/adding_new_operation_how_to.md
@@ -153,11 +153,11 @@ At this point, you will now have a safe Rust interface for the PSA operation you
 
 Add the new operation to the correct
 [provider](https://github.com/parallaxsecond/parsec/tree/master/src/providers) (in this case, [Mbed
-Crypto](https://github.com/parallaxsecond/parsec/tree/master/src/providers/mbed_provider)) as a
-`psa_xxx_internal` method. The operation method should take the user inputs, arrange them in a way
+Crypto](https://github.com/parallaxsecond/parsec/tree/master/src/providers/mbed_crypto_provider)) as
+a `psa_xxx_internal` method. The operation method should take the user inputs, arrange them in a way
 that [`psa-crypto`](#psa-crypto) accepts, and provide any extra logic or storage if required (e.g.
 an output buffer). The external implementation is to be added to the provider’s
-[`mod.rs`](https://github.com/parallaxsecond/parsec/blob/master/src/providers/mbed_provider/mod.rs)
+[`mod.rs`](https://github.com/parallaxsecond/parsec/blob/master/src/providers/mbed_crypto_provider/mod.rs)
 file, which outputs a trace entry and passes the call back to the internal implementation.
 
 A default implementation is added to

diff --git a/src/parsec_service/README.md b/src/parsec_service/README.md
@@ -20,7 +20,7 @@ They cover the following concepts:
    and running the service
 - [Installation](install_parsec_linux.md) - installing Parsec as a systemd daemon
 - [Configuration](configuration.md) - how to configure Parsec
-- [Testing](test.md) - details about the kinds of tests we employ and how to set up your environment
+- [Testing](tests) - details about the kinds of tests we employ and how to set up your environment
    in preparation for running them
 
 *Copyright 2019 Contributors to the Parsec project.*
diff --git a/src/parsec_service/build_run.md b/src/parsec_service/build_run.md
@@ -18,7 +18,7 @@ one](https://github.com/parallaxsecond/parsec/blob/master/e2e_tests/provider_cfg
 The `mbed-crypto-provider` feature is going to be used as an example in this guide. This can be
 replaced by a subset of the features mentioned above, space or comma separated. If you would like to
 test the TPM or PKCS check the [related
-guides](test.md#testing-the-tpm-provider-using-the-software-tpm).
+guides](tests#testing-the-tpm-provider-using-the-software-tpm).
 
 For the `DomainSocket` listener, the socket folder needs to be created:
 
@@ -51,8 +51,8 @@ via a command-line argument:
 cargo run --features mbed-crypto-provider -- --config e2e_tests/provider_cfg/mbed-crypto/config.toml
 ```````
 
-From another terminal, it is now possible to execute the [end-to-end
-tests](test.md#end-to-end-tests) on Parsec!
+From another terminal, it is now possible to execute the [end-to-end tests](tests#end-to-end-tests)
+on Parsec!
 
 ```````
 cd e2e_tests

diff --git a/src/parsec_service/test.md → src/parsec_service/tests/README.md b/src/parsec_service/test.md → src/parsec_service/tests/README.md
diff --git a/src/parsec_service/tests/existing_tests.md b/src/parsec_service/tests/existing_tests.md
@@ -0,0 +1,50 @@
+# List of existing tests
+
+## End-to-end testing
+
+These tests are meant to be executed on a running Parsec service and using a Parsec client to
+communicate to it. The
+[`parsec/e2e_tests`](https://github.com/parallaxsecond/parsec/tree/master/e2e_tests) crate contains
+a test client based on the Rust client that is used inside the tests written in
+[`parsec/e2e_tests/tests`](https://github.com/parallaxsecond/parsec/tree/master/e2e_tests/tests).
+
+The end-to-end tests contain tests to be executed: * with a Parsec service containing a single
+provider:
+[`per_provider`](https://github.com/parallaxsecond/parsec/tree/master/e2e_tests/tests/per_provider)
+tests * with a Parsec service containing all providers:
+[`all_providers`](https://github.com/parallaxsecond/parsec/tree/master/e2e_tests/tests/all_providers)
+and [`config`](https://github.com/parallaxsecond/parsec/tree/master/e2e_tests/tests/config) tests
+
+The
+[`parsec/e2e_tests/provider_cfg`](https://github.com/parallaxsecond/parsec/tree/master/e2e_tests/provider_cfg)
+folder contain the `Dockerfile` and Parsec configuration needed to run Parsec for the corresponding
+tests.
+
+| Name                                                                                                                                     | Description                                                                                                                                                                             |
+|------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| [All providers e2e tests](https://github.com/parallaxsecond/parsec/tree/master/e2e_tests/tests/all_providers)                            | End-to-end tests on a service with all providers. Mostly to test core operations.                                                                                                       |
+| [Cross-providers e2e tests](https://github.com/parallaxsecond/parsec/tree/master/e2e_tests/tests/all_providers/cross.rs)                 | Test that the output of various operations from different providers is accepted by the other providers.                                                                                 |
+| [Configuration e2e tests](https://github.com/parallaxsecond/parsec/tree/master/e2e_tests/tests/config)                                   | These check if the behaviour of the service is correct before and after reloading with a different configuration.                                                                       |
+| [Per provider normal tests](https://github.com/parallaxsecond/parsec/tree/master/e2e_tests/tests/per_provider/normal_tests)              | E2E tests checking most cryptographic operations on a single provider. Parsec results are also verified with third party software crypto implementations (ring, the rsa crate, etc...). |
+| [Per provider persistence tests](https://github.com/parallaxsecond/parsec/tree/master/e2e_tests/tests/per_provider/persistent_before.rs) | E2E tests checking correct behaviour of the service around persistence of keys in the Key Info Manager.                                                                                 |
+| [Per provider stress tests](https://github.com/parallaxsecond/parsec/tree/master/e2e_tests/tests/per_provider/stress_test.rs)            | Stress tests executing a large number of canonical operations at high frequency on a single provider.                                                                                   |
+
+## Fuzz testing
+
+| Name                                                                      | Description                                                                   |
+|---------------------------------------------------------------------------|-------------------------------------------------------------------------------|
+| [Fuzz testing](https://github.com/parallaxsecond/parsec/tree/master/fuzz) | Tests sending random requests to the service and waiting it to crash/timeout. |
+
+## Unit testing
+
+| Name                                                                                                                                | Description                                                                                                                              |
+|-------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------|
+| [Direct authenticator tests](https://github.com/parallaxsecond/parsec/blob/master/src/authenticators/direct_authenticator/mod.rs)   | Testing the `Authenticate` trait with this authenticator.                                                                                |
+| [On-disk key info manager tests](https://github.com/parallaxsecond/parsec/blob/master/src/key_info_managers/on_disk_manager/mod.rs) | Testing the `ManageKeyInfo` trait with various strings for application and key names. The persistence is tested in the end-to-end tests. |
+
+## In dependencies
+
+The dependencies that we maintain in the `parallaxsecond` organisation also contain their own set of
+integration and unit tests: `parsec-interface-rs`, `rust-psa-crypto` and `rust-tss-esapi`.
+
+*Copyright 2020 Contributors to the Parsec project.*