squash - Using the testing environment

docs/developers/testing.md

@@ -202,7 +202,9 @@ Add the Python test to an existing Python test suite found in the core test list
 
 The iRODS Testing Environment is a Docker Compose-based project written in Python that is used by the Consortium to test the iRODS server and its plugins. The Testing Environment is driven by a series of scripts to run the tests on a number of different platforms with various database backends and other configuration options. This is the primary tool used for day-to-day testing for iRODS developers as well as for verification in releasing the iRODS server. In addition to running tests, the Compose projects can be useful for manually testing things and quickly deploying specific environments for reproducing issues or developing a proof of concept.
 
-This documentation will briefly describe a few useful ways to employ the iRODS Testing Environment. The README in the project's GitHub repository provides extensive details on the purpose and usage for the various scripts: [https://github.com/irods/irods_testing_environment/blob/main/README.md](https://github.com/irods/irods_testing_environment/blob/main/README.md) Each script available in the project also has help text available with the `--help` option which describes the available options and their purposes.
+This documentation will briefly describe a few useful ways to employ the iRODS Testing Environment. The README in the project's GitHub repository provides extensive details on the purpose and usage of the various scripts: [https://github.com/irods/irods_testing_environment/blob/main/README.md](https://github.com/irods/irods_testing_environment/blob/main/README.md)
+
+Each script available in the project also has help text available with the `--help` option which describes the available options and their purposes.
 
 ### Getting started
 
@@ -211,7 +213,6 @@ In order to configure your environment to use the iRODS Testing Environment, usi
 virtualenv -p python3 ~/irods_testing_environment
 source ~/irods_testing_environment/bin/activate
 pip install docker-compose GitPython
-pip freeze
 ```
 
 #### If you cannot install `docker-compose` ...
@@ -235,7 +236,7 @@ At this point, you can make the modifications needed to fix any problems you may
 
 Once done, back out and pip install the local directory:
 ```bash
-cd -
+cd ..
 pip install ./compose
 ```
 
@@ -245,17 +246,17 @@ pip install ./compose
 
 Here is the minimal form for running the test suite for a particular `OS`, `OS_VERSION`, `DATABASE`, and `DATABASE_VERSION`:
 ```
-python run_core_tests.py --project-directory projects/OS-OS_VERSION/OS-OS_VERSION-DATABASE-DATABASE_VERSION
+python run_core_tests.py --project-directory projects/${OS}-${OS_VERSION}/${OS}-${OS_VERSION}-${DATABASE}-${DATABASE_VERSION}
 ```
 
 This will serially run the entire test suite using the latest release of the iRODS server. This will create a container for the iRODS server configured as the sole catalog service provider, a container for the database where the catalog is stored, and a network so that they can communicate as if it were a distributed environment.
 
 #### Using locally built iRODS packages
 
-The `--irods-package-directory` option allows the user to provide iRODS packages as files on the host machine. This is the standard way for iRODS developers to test modifications to the iRODS server software:
+The `--irods-package-directory` option allows the user to provide iRODS packages as files on the host machine. This is the standard way for iRODS developers to test modifications to the iRODS server software before it is released:
 ```
 python run_core_tests.py \
-    --project-directory projects/OS-OS_VERSION/OS-OS_VERSION-DATABASE-DATABASE_VERSION \
+    --project-directory projects/${OS}-${OS_VERSION}/${OS}-${OS_VERSION}-${DATABASE}-${DATABASE_VERSION} \
     --irods-package-directory /path/to/directory/containing/irods/package/files
 ```
 
@@ -264,7 +265,7 @@ python run_core_tests.py \
 The `--concurrent-test-executors` option allows the user to specify how many iRODS zones to deploy and use for splitting up the list of tests to run. Note that this option can quickly increase the number of containers created by the Compose project (2 containers per test executor), so make sure to choose a number appropriate to the host system's capabilities. Here is an example of how to use the option:
 ```
 python run_core_tests.py \
-    --project-directory projects/OS-OS_VERSION/OS-OS_VERSION-DATABASE-DATABASE_VERSION \
+    --project-directory projects/${OS}-${OS_VERSION}/${OS}-${OS_VERSION}-${DATABASE}-${DATABASE_VERSION} \
     --concurrent-test-executors 4
 ```
 This will deploy 4 iRODS zones (4 * (1 catalog service provider + 1 database) = 8 containers) and will run tests from the list of tests by taking them from a queue and concurrently executing on the catalog service providers in each zone.
@@ -276,39 +277,39 @@ The test suite takes 8-10 hours to complete when run serially. With 4 concurrent
 The `--tests` option allows the user to specify a space-delimited list of specific tests to run. Here is an example of how to use the option:
 ```
 python run_core_tests.py \
-    --project-directory projects/OS-OS_VERSION/OS-OS_VERSION-DATABASE-DATABASE_VERSION \
+    --project-directory projects/${OS}-${OS_VERSION}/${OS}-${OS_VERSION}-${DATABASE}-${DATABASE_VERSION} \
     --tests test_ils test_icp test_ihelp
 ```
-This will deploy a single iRODS zone and execute the following tests in order on the catalog service provider: `test_ils`, `test_icp`, and `test_ihelp`. This can be used in conjunction with the `--concurrent-test-executors` option, but the tests will not be run in a deterministic order as the concurrent executors will take tests from the queue as they complete them.
+This will deploy a single iRODS zone and execute the following tests in order on the catalog service provider: `test_ils`, `test_icp`, and `test_ihelp`. This can be used in conjunction with the `--concurrent-test-executors` option, but the tests will not be run in a deterministic order as the concurrent executors will take tests from the queue as they complete earlier tests.
 
 ### How to run unit tests: `run_unit_tests.py`
 
 `run_unit_tests.py` is the main script for running the iRODS "unit" test suite (see [Unit test suite](#unit-test-suite-catch2)).
 
 Here is the minimal form for running the test suite for a particular `OS`, `OS_VERSION`, `DATABASE`, and `DATABASE_VERSION`:
 ```
-python run_unit_tests.py --project-directory projects/OS-OS_VERSION/OS-OS_VERSION-DATABASE-DATABASE_VERSION
+python run_unit_tests.py --project-directory projects/${OS}-${OS_VERSION}/${OS}-${OS_VERSION}-${DATABASE}-${DATABASE_VERSION}
 ```
 
-This will serially run the unit test suite using the latest release of the iRODS server. This will create a container for the iRODS server configured as the sole catalog service provider, a container for the database where the catalog is stored, and a network so that they can communicate as if it were a distributed environment. A running iRODS server is required because the Catch2 tests are not actually unit tests. Most of the same options available for `run_core_tests.py` are available for this script as well.
+This will serially run the unit test suite using the latest release of the iRODS server. This will create a container for the iRODS server configured as the sole catalog service provider, a container for the database where the catalog is stored, and a network so that they can communicate as if it were a distributed environment. A running iRODS server is required because the Catch2 tests are not actually unit tests. Most of the same options available for `run_core_tests.py` are also available for this script.
 
 The longest unit test takes about 2 minutes to complete.
 
 ### How to stand up an iRODS zone: `stand_it_up.py`
 
-`stand_it_up.py` simply stands up an iRODS zone as specified. The minimal iRODS zone is a single catalog service provider and the database with which is communicates to maintain the catalog. This is the default behavior for this script.
+`stand_it_up.py` simply stands up an iRODS zone as specified. The minimal iRODS zone is a single catalog service provider and the database with which it communicates to maintain the catalog. The default behavior of this script is this: create a container for the iRODS server configured as the sole catalog service provider, a container for the database where the catalog is stored, and a network so that they can communicate as if it were a distributed environment.
 
 Here is the minimal form for creating a minimal iRODS zone using the latest release of the iRODS server for a particular `OS`, `OS_VERSION`, `DATABASE`, and `DATABASE_VERSION`:
 ```
-python stand_it_up.py --project-directory projects/OS-OS_VERSION/OS-OS_VERSION-DATABASE-DATABASE_VERSION
+python stand_it_up.py --project-directory projects/${OS}-${OS_VERSION}/${OS}-${OS_VERSION}-${DATABASE}-${DATABASE_VERSION}
 ```
 
 #### Adding catalog service consumers
 
 The `--consumer-instance-count` option allows the user to specify how many catalog service consumers to deploy alongside the catalog service provider (of which there can only be one at this time). Here is an example of how to use the option:
 ```
 python run_core_tests.py \
-    --project-directory projects/OS-OS_VERSION/OS-OS_VERSION-DATABASE-DATABASE_VERSION \
-    --consumer-instane-count 3
+    --project-directory projects/${OS}-${OS_VERSION}/${OS}-${OS_VERSION}-${DATABASE}-${DATABASE_VERSION} \
+    --consumer-instance-count 3
 ```
-This will deploy a single iRODS zone with 1 catalog service provider, 1 database instance, and 3 catalog service consumers (5 containers).
+This will deploy a single iRODS zone with 1 catalog service provider, 1 database instance, and 3 catalog service consumers (a total of 5 containers).