Updates docs to better describe building the client, testing, and rel…

…ated repos. Added readme to client folder. (#1200)

client/README.md

@@ -0,0 +1,17 @@
+# STIG Manager Reference UI
+
+The reference UI client provided by the project is implemented as a Single Page Application (SPA) using ExtJS 3.4.  It exercises most, but not all of the API endpoints. 
+
+## Setting Up the Client for Development
+
+- From the `/client/src/js/third-party/` directory, run `npm ci` to install the required dependencies.
+- For development, in most cases the API configuration should specify the following envvar and value: `STIGMAN_CLIENT_DIRECTORY: "../../client/src"`.
+
+
+## Building the Client for Distribution
+
+Requires:
+- nodejs
+- uglify-js
+
+From the `/client` directory, run the `build.sh` bash script.  The output will be in the `/client/dist` directory.

docs/the-project/clients.rst

@@ -14,10 +14,13 @@ STIG Manager OSS Reference GUI
 ---------------------------------
 A GUI client that makes use of the Project API is available in our Repo.  Its features are described elsewhere in this documentation. 
 
+See the client `README.md <https://github.com/NUWCDIVNPT/stig-manager/tree/main/client/README.md>`_ for more information on developing or building the client.
+
+
 
 STIG Manager Watcher
 -------------------------
-A command-line client that will monitor a file-system directory and upload .ckls or XCCDF results to a STIG Manager API instance: `STIG Manger Watcher. <https://github.com/NUWCDIVNPT/stigman-watcher>`_  It is maintained by the main STIGMan OSS dev group, and also available as `an npm package. <https://www.npmjs.com/package/stigman-watcher>`_  Check the gitHub repo's `wiki for further documentation. <https://github.com/NUWCDIVNPT/stigman-watcher/wiki>`_
+A command-line client that will monitor a file-system directory and upload .ckl/.cklb or XCCDF results to a STIG Manager API instance: `STIG Manger Watcher. <https://github.com/NUWCDIVNPT/stigman-watcher>`_  It is maintained by the main STIGMan OSS dev group, and also available as `an npm package. <https://www.npmjs.com/package/stigman-watcher>`_  Check the gitHub repo's `wiki for further documentation. <https://github.com/NUWCDIVNPT/stigman-watcher/wiki>`_
 
 Proposed Clients
 ====================
@@ -35,8 +38,21 @@ Several additional Clients may be found useful, but are not a priority for devel
 Create a new Client for the STIG Manager API
 ==================================================
 
-STIG Manager API was created so that other clients could take advantage of the data it manages, though currently, the only one available is the Client provided as part of the project repo.
+The STIG Manager API was created so that other clients could take advantage of the data it manages. `The API is fully defined using the OpenAPI 3.0.1 specification here. <https://github.com/NUWCDIVNPT/stig-manager/blob/main/api/source/specification/stig-manager.yaml>`_ 
+
+Clients will need to authenticate with the OpenID Connect Identity provider their target API is configured to use.  Particular authentication flows and configurations supported may vary by deployment. 
+
+
+Client Development Resources
+==================================================
+
+The STIG Manager team maintains a separate repository containing useful javascript modules for developing clients.  These modules are used in both the STIG Manager GUI and STIGMan Watcher, and are provided as a resource to assist the creation of clients that import checklist files or batch updates to the API. 
 
-For now, please use our existing Clients as a reference for how to do this.  If more information is required, please let us know in an Issue on our Repo and we will do our best to assist.
+These modules are available `in the stig-manager-client-modules repository. <https://github.com/NUWCDIVNPT/stig-manager-client-modules>`_  Check the gitHub repo's README.md and documentation for more specific information about using them.
 
+ - `ReviewParser.js` Provides parsers for .ckl, .cklb, and XCCDF data.  These modules will process data in the checklist format specified, and return a JSON object that can be used to create or update Assets, STIG Assignments, and Reviews in the STIG Manager API. The parsers incorporate processing that will ensure Reviews conform to the Import Options specified by the target Collections in the API, if specified.  
+    - reviewsFromCkl
+    - reviewsFromCklb
+    - reviewsFromXccdf
+ - `TaskObject.js` Takes parsed checklist data, as well as the current state of a Collection's Assets and the STIGs available in the system, and create a TaskObject. The TaskObject defines Assets and Assignments that need to be created or updated, as well as the Reviews that were identified in the parsed checklist data for those Assets.
 

docs/the-project/related-repos.rst

@@ -29,3 +29,17 @@ The STIG Manager Demonstration Orchestration offers a sample configuration for a
 See the `STIGMan Orchestration <https://github.com/NUWCDIVNPT/stigman-orchestration>`_ for more details. 
 
 
+STIGMan Client Modules
+==================================================
+
+The STIG Manager team maintains a separate repository containing useful javascript modules for developing clients.  These modules are used in both the STIG Manager GUI and STIGMan Watcher, and are provided as a resource to assist the creation of clients that import checklist files or batch updates to the API. 
+
+These modules are available `in the stig-manager-client-modules repository. <https://github.com/NUWCDIVNPT/stig-manager-client-modules>`_  Check the gitHub repo's README.md and documentation for more specific information about using them.
+
+ - `ReviewParser.js` Provides parsers for .ckl, .cklb, and XCCDF data.  These modules will process data in the checklist format specified, and return a JSON object that can be used to create or update Assets, STIG Assignments, and Reviews in the STIG Manager API. The parsers incorporate processing that will ensure Reviews conform to the Import Options specified by the target Collections in the API, if specified.  
+    - reviewsFromCkl
+    - reviewsFromCklb
+    - reviewsFromXccdf
+ - `TaskObject.js` Takes parsed checklist data, as well as the current state of a Collection's Assets and the STIGs available in the system, and create a TaskObject. The TaskObject defines Assets and Assignments that need to be created or updated, as well as the Reviews that were identified in the parsed checklist data for those Assets.
+
+

docs/the-project/testing.rst

@@ -1,12 +1,10 @@
 .. _testing:
 
 
-Testing Guide
+API Testing Guide
 ########################################
 
 
-
-
 The STIG Manager project currently tests its API using a Postman Collection and specific test data, which can be found in the repo.
 
 The Postman Collection tests are run automatically with Newman whenever a Pull Request is made to the project.
@@ -16,5 +14,7 @@ The tests run in several iterations, simulating Users accessing the system with
 
 
 
+Running the API Tests Locally
+=============================================
 
-
+See the test `README.md <https://github.com/NUWCDIVNPT/stig-manager/tree/main/test/api/README.md>`_ for more information on running the tests and test data.

test/api/README.md

@@ -3,9 +3,10 @@
 ## Required tooling
 - Node.js
 - [newman](https://www.npmjs.com/package/newman) (global install)
+- [newman-reporter-htmlextra](https://www.npmjs.com/package/newman-reporter-htmlextra)
+
 
 ## Optional tooling
-- [newman-reporter-htmlextra](https://www.npmjs.com/package/newman-reporter-htmlextra)
 - [Postman](https://www.postman.com/downloads/)
 
 ## Runtime environment
@@ -18,7 +19,6 @@ Run ***ONE*** of the following:
    ```
 
 
-
 - An HTTP server on port 8080 that accepts requests for the content in `./mock-keycloak`
 
    > Example with Python3:
@@ -42,7 +42,8 @@ Run ***ONE*** of the following:
    ```
 
 ### API
-- Run the API so it can communicate with the Authentication Server and database and is listening on port 64001
+- Run the API so it answering requests at `localhost:64001/api`, and can communicate with the Authentication Server and database.
+- The API can be run in a dev environment such as Visual Studio Code or in a container
 
    > Example with docker
    ```
@@ -53,25 +54,35 @@ Run ***ONE*** of the following:
 
 ## Running the Tests
 
+### From the Command Line Using newman
+- Ensure the newman npm module is installed. If not, run `npm install -g newman`
+- From the /test/api folder of the project repo, run the `runFailsOnly.sh` bash script.
+- Test result summaries are output to the console, and detailed test reports are output to the `/test/api/newman`` directory.
+
+### From Postman UI
+
+- Open Postman and import the collection and environment files from the `/test/api` directory of the project repo.
+- Run requests individually, or as part of a Collection or Folder "run" using the `collectionRunnerData.json` file, if user iterations are needed.
+
+
+## Test Components
+
+Located in the `/test/api directory of the project repo:
+
+- `postman_collection.json`  The Postman Collection of API tests.
+- `postman_environment.json`  The Postman Environment for the API tests.
+- `collectionRunnerData.json`  The data file used by the newman/Postman Collection Runner to run iterations of the tests. Each iteration is specific to a user with different levels of access and grants to Collections maintained by the API. 
+- `runFailsOnly.sh`  A bash script that runs the tests using newman, and outputs a summary of the results to the console. Detailed test reports are output to the /test/api/newman directory.  Tests are run in groups defined by the top-level folders of the Postman Collection. 
+- `form-data-files/*`  Test data files sent by Postman/newman to the API. Includes several sets of data to populate the API with data the tests expect, and several reference STIGs to use in the tests.  If using the Postman UI, you may need to adjust Postman settings to allow access to this folder locally. 
+
+## Test Policy
+
+- All PRs to the project repo must pass all API tests before they will be accepted.
+- All PRs to the project repo should include new or updated API tests that cover the changes made by the PR to the API.
 
-```
-newman run postman_collection.json -e postman_environment.json -d collectionRunnerData.json -n 1 \
-  --folder "LoadTestData" -r cli,htmlextra  \
-  --reporter-htmlextra-export \
-  ./newman/dataPreloadReport.html
+## Test Coverage
 
-newman run postman_collection.json -e postman_environment.json -d collectionRunnerData.json -n 7 \
-  --folder "GETs" -r cli,htmlextra \
-  --reporter-htmlextra-export \
-  ./newman/GetsReport.html
+- The API tests cover all endpoints of the API, and all HTTP methods supported by the API.
+- The PR Workflow running the tests will also generate a coverage report showing how much of the API code is covered by the tests.
 
-newman run postman_collection.json -e postman_environment.json -d collectionRunnerData.json -n 7 \
-  --folder "POSTS, Puts, Patches, and Deletes" -r cli,htmlextra \
-  --reporter-htmlextra-export \
-  ./newman/PPPDReport.html
 
-newman run postman_collection.json -e postman_environment.json -d collectionRunnerData.json -n 2 \
---folder "STIGS" -r cli,htmlextra \
---reporter-htmlextra-export \
-./newman/stigsReport.html
-```