Improve the testing README

Author: sanason

features/README.md

@@ -3,16 +3,74 @@
 The automated tests for the DAP code are implemented using [cucumber-js](https://github.com/cucumber/cucumber-js)
 and [puppeteer](https://pptr.dev/).
 
-By default the tests use the local version of the DAP javascript files. Loading
-the code into a test HTML page, performing various user actions, and testing
-the behavior of the code in response to the user actions.
+```mermaid
+---
+title: Testing architecture
+---
+
+flowchart LR
+    Runner("`Test Runner<br>*Cucumber.js*`"):::local
+    Puppeteer("`Browser Automation<br>*Puppeteer*`"):::local
+    Browser(Chromium):::local
+    Site("`Test Website<br>*nginx in Docker*`"):::local
+    config_startup@{ shape: diamond, label: "Configurable at<br>website startup" }
+subgraph code [DAP code]
+DAP_Local(DAP code - local):::local
+DAP_Staging(DAP code - staging):::remote
+DAP_Prod(DAP code - production):::remote
+end
+GA4(DAP GA4 test property):::remote
+subgraph Legend
+legend_local(Running locally):::local
+legend_remote(Running remotely):::remote
+end
+
+classDef local fill:#f96
+classDef remote fill:#f9f
+
+Runner -->|drives| Puppeteer -->|controls| Browser -->|loads| Site
+config_startup --> DAP_Local
+config_startup --> DAP_Staging
+config_startup --> DAP_Prod
+Site-.->|sends events to| GA4
+Site -->|loads one of|config_startup
+```
+
+## Running the test site
+The test site is a simple nginx server running in a Docker container. It serves static HTML pages that include the DAP code, allowing us to test the DAP code's behavior in a realistic environment.
+
+To start up the test site, run one of the `test-site-*` commands:
+
+```bash
+npm run test-site-dev
+```
+This particular command will start up the test site at http://localhost:8080/. All pages will be configured to use your local version of the DAP code by including the script tag:
+
+```angular2html
+<script async id="_fed_an_ua_tag" src="Universal-Federated-Analytics-Min.js"></script>
+```
+
+You can also choose to run the test site configured to load a deployed version of the DAP code, either the staging or production version, by running `npm run test-site-stg` or `npm run test-site-prd`, respectively.
+
+## Configuring DAP in the test site
+The DAP code is configurable at load time via query parameters. For instance, to enable DAP's YouTube tracking, a website
+can load the DAP code with the `yt` query parameter set to `true`.
+
+```angular2html
+<script async type="text/javascript" id="_fed_an_ua_tag" src="https://dap.digitalgov.gov/Universal-Federated-Analytics-Min.js?agency=HHS&yt=true"></script>
+```
+
+The full list of configurable options is available in the [DAP Code Capabilities Summary](https://github.com/digital-analytics-program/gov-wide-code/wiki/DAP-Code-Capabilities-Summary).
+
+The test site is designed to pass through query parameters to the DAP code, allowing you to test different DAP configurations by changing the URL. 
+For instance, opening http://localhost:8080/youtube.html?yt=true&search=nasa will load the page for testing DAP's YouTube tracking with YouTube tracking enbabled.
+Any query parameters that don't match one of DAP's configuration options will be treated as a normal query parameter (e.g. `search=nasa`).
 
-Use the `DAP_ENV` environment variable to insert live versions of the code into
-the test HTML page instead of the local version as described below.
+This capability is used extensively in the automated tests to check the DAP code's behavior in various configurations.
 
 ## Running the tests
 
-Start up the test site at http://localhost:8080/:
+Start up the test site using any of the `test-site-*` commands:
 
 ```bash
 npm run test-site-dev
@@ -38,24 +96,11 @@ npm run cucumber:report
 
 Test report should be available in `output/test-results.html`.
 
-## Configuring with environment variables
+### Running the tests in verbose mode
 
-### Verbose mode
-
-Print debugging information to stdout while running the tests:
+Verbose mode logs events that occur within the browser during test execution. If you find yourself wishing that you could
+watch what's happening in browser devtools during test execution, try verbose mode:
 
 ```bash
 VERBOSE=true npm run cucumber
 ```
-
-### Run tests against the live staging environment
-
-```bash
-DAP_ENV=staging npm run cucumber
-```
-
-### Run tests against the live production environment
-
-```bash
-DAP_ENV=production npm run cucumber
-```