FI-2950: Improve test description (#546)

* Improve token introspection description.

* Improve suite description.

* Fix typos.

* Improve suite descriptions of first three scenarios.

* Improve descriptions of single patient api scenarios.

* Improve multipatient description and additional tests description.

* Make high level scenario descriptions more consistent and helpful.

* Improve 9.13 description.

* Update fine grained scope test description.

* Update smart granular scope selection.

* Fix rubocop.

lib/onc_certification_g10_test_kit.rb

@@ -257,13 +257,37 @@ def self.well_known_route_handler
     )
 
     description %(
-      The ONC Certification (g)(10) Standardized API Test Kit is a testing tool for
-      Health Level 7 (HL7®) Fast Healthcare Interoperability Resources (FHIR®)
-      services seeking to meet the requirements of the Standardized API for
-      Patient and Population Services criterion § 170.315(g)(10) in the ONC Certification Program.
-
-      To get started, please first register the Inferno client as a SMART App
-      with the following information:
+      The ONC Certification (g)(10) Standardized API Test Suite is a testing
+      tool for Health Level 7 (HL7®) Fast Healthcare Interoperability Resources
+      (FHIR®) services seeking to meet the requirements of the Standardized API
+      for Patient and Population Services criterion § 170.315(g)(10) in the ONC
+      Certification Program.
+
+      This test suite is organized into testing scenarios that in sum cover all
+      requirements within the § 170.315(g)(10) certification criterion.  The
+      scenarios are intended to be run in order during certification, but can
+      be run out of order to support testing during development or certification
+      preparation.  Some scenarios depend on data collected during previous
+      scenarios to function.  In these cases, the scenario description describes
+      these dependencies.
+
+      The best way to learn about how to use these tests is the
+      [(g)(10) Standardized API Test Kit walkthrough](https://github.com/onc-healthit/onc-certification-g10-test-kit/wiki/Walkthrough),
+      which demonstrates the tests running against a simulated system.
+
+      The first three scenarios require the system under test to demonstrate
+      basic SMART App Launch functionality.  The fourth uses a valid token
+      provided during earlier tests to verify support for the Single Patient API
+      as described in the criterion.  The fifth verifies support for the Multi
+      Patient API, including Backend Services for authorization.  Not all
+      authorization-related requirements are verified in the first three
+      scenarios, and the 'Additional Authorization Tests' verify these
+      additional requirements.  The last scenario contains a list of
+      'attestations' and 'visual inspections' for requirements that could not
+      be verified through automated testing.
+
+      To get started with the first group of scenarios, please first register the
+      Inferno client as a SMART App with the following information:
 
       * SMART Launch URI: `#{SMARTAppLaunch::AppLaunchTest.config.options[:launch_uri]}`
       * OAuth Redirect URI: `#{SMARTAppLaunch::AppRedirectTest.config.options[:redirect_uri]}`
@@ -273,7 +297,7 @@ def self.well_known_route_handler
 
       * `#{Inferno::Application[:base_url]}/custom/g10_certification/.well-known/jwks.json`
 
-      Systems must pass all tests in order to qualify for ONC certification.
+      Systems must pass all tests to qualify for ONC certification.
     )
 
     suite_summary %(
@@ -324,11 +348,19 @@ def self.well_known_route_handler
       title 'Additional Authorization Tests'
       id 'Group06'
       description %(
-        Not all requirements that need to be tested fit within the previous
-        scenarios. The tests contained in this section addresses remaining
-        testing requirements. Each of these tests need to be run independently.
-        Please read the instructions for each in the 'About' section, as they
-        may require special setup on the part of the tester.
+        The (g)(10) Standardized Test Suite attempts to minimize effort required
+        by testers by creating scenarios that validate as many requirements as
+        possible with just a handful of SMART App Launches.  However, not all
+        SMART App Launch and (g)(10) Standardized API criterion requirements
+        that need to be verified fit within the first few test scenarios in this
+        suite.
+
+        The scenarios contained in this section verify remaining testing
+        requirements for the (g)(10) Standardized API criterion relevant to
+        the SMART App Launch implementation specification. Each of these scenarios
+        need to be run independently.  Please read the instructions for each in
+        the 'About' section, as they may require special setup on the part of
+        the tester.
       )
 
       default_redirect_message_proc = lambda do |auth_url|

lib/onc_certification_g10_test_kit/multi_patient_api_stu1.rb

@@ -21,20 +21,25 @@ class MultiPatientAPIGroupSTU1 < Inferno::TestGroup
     )
 
     description %(
-      Demonstrate the ability to export clinical data for multiple patients in a
-      group using [FHIR Bulk Data Access
-      IG](http://hl7.org/fhir/uv/bulkdata/STU1.0.1/). This test uses [Backend
-      Services
+      This scenario verifies the ability of the system to export clinical data
+      for multiple patients in a group using [FHIR Bulk Data Access
+      IG](http://hl7.org/fhir/uv/bulkdata/STU1.0.1/). This scenario uses
+      [Backend Services
       Authorization](http://hl7.org/fhir/uv/bulkdata/STU1.0.1/authorization/index.html)
       to obtain an access token from the server. After authorization, a group
-      level bulk data export request is initialized. Finally, this test reads
-      exported NDJSON files from the server and validates the resources in each
-      file. To run the test successfully, the selected group export is required
-      to have resources conforming to every profile mapped to [USCDI data
+      level bulk data export request is initialized. Finally, this scenario
+      reads exported NDJSON files from the server and validates the resources in
+      each file. To run the test successfully, the selected group export is
+      required to have resources conforming to every profile mapped to [USCDI
+      data
       elements](https://www.healthit.gov/isa/us-core-data-interoperability-uscdi).
       Additionally, it is expected the server will provide Encounter, Location,
       Organization, and Practitioner resources as they are referenced as must
       support elements in required resources.
+
+      Prior to executing this scenario, register Inferno with the following JWK Set Url:
+
+      * `#{Inferno::Application[:base_url]}/custom/g10_certification/.well-known/jwks.json`
     )
     id :multi_patient_api
     run_as_group

lib/onc_certification_g10_test_kit/multi_patient_api_stu2.rb

@@ -21,20 +21,25 @@ class MultiPatientAPIGroupSTU2 < Inferno::TestGroup
     )
 
     description %(
-      Demonstrate the ability to export clinical data for multiple patients in a
-      group using [FHIR Bulk Data Access
-      IG](https://hl7.org/fhir/uv/bulkdata/STU2/). This test uses [Backend
+      This scenario verifies the ability of the system to export clinical data
+      for multiple patients in a group using [FHIR Bulk Data Access
+      IG](https://hl7.org/fhir/uv/bulkdata/STU2/). This scenario uses [Backend
       Services
       Authorization](http://www.hl7.org/fhir/smart-app-launch/backend-services.html)
       to obtain an access token from the server. After authorization, a group
-      level bulk data export request is initialized. Finally, this test reads
-      exported NDJSON files from the server and validates the resources in each
-      file. To run the test successfully, the selected group export is required
-      to have resources conforming to every profile mapped to [USCDI data
+      level bulk data export request is initialized. Finally, this scenario
+      reads exported NDJSON files from the server and validates the resources in
+      each file. To run the test successfully, the selected group export is
+      required to have resources conforming to every profile mapped to [USCDI
+      data
       elements](https://www.healthit.gov/isa/us-core-data-interoperability-uscdi).
       Additionally, it is expected the server will provide Encounter, Location,
       Organization, and Practitioner resources as they are referenced as must
       support elements in required resources.
+
+      Prior to executing this scenario, register Inferno with the following JWK Set Url:
+
+      * `#{Inferno::Application[:base_url]}/custom/g10_certification/.well-known/jwks.json`
     )
     id :multi_patient_api_stu2
     run_as_group

lib/onc_certification_g10_test_kit/single_patient_api_group.rb

@@ -8,8 +8,13 @@ class SinglePatientAPIGroup < Inferno::TestGroup
     title 'Single Patient API (US Core 3.1.1)'
     short_title 'Single Patient API'
     description %(
+      This scenario verifies the ability of a system to provide a 'Single Patient API'
+      as described in the (g)(10) Standardized API certification criterion.
+      Prior to running this scenario, systems must recieve a verified access token
+      from one of the previous SMART App Launch scenarios.
+
       For each of the relevant USCDI data elements provided in the
-      CapabilityStatement, this test executes the [required supported
+      CapabilityStatement, this scenario executes the [required supported
       searches](http://www.hl7.org/fhir/us/core/STU3.1.1/CapabilityStatement-us-core-server.html)
       as defined by the US Core Implementation Guide v3.1.1.
 

lib/onc_certification_g10_test_kit/single_patient_us_core_4_api_group.rb

@@ -6,8 +6,13 @@ class SinglePatientUSCore4APIGroup < Inferno::TestGroup
     title 'Single Patient API (US Core 4.0.0)'
     short_title 'Single Patient API'
     description %(
+      This scenario verifies the ability of a system to provide a 'Single Patient API'
+      as described in the (g)(10) Standardized API certification criterion.
+      Prior to running this scenario, systems must recieve a verified access token
+      from one of the previous SMART App Launch scenarios.
+
       For each of the relevant USCDI data elements provided in the
-      CapabilityStatement, this test executes the [required supported
+      CapabilityStatement, this scenario executes the [required supported
       searches](http://hl7.org/fhir/us/core/STU4/CapabilityStatement-us-core-server.html)
       as defined by the US Core Implementation Guide v4.0.0.
 

lib/onc_certification_g10_test_kit/single_patient_us_core_6_api_group.rb

@@ -6,8 +6,13 @@ class SinglePatientUSCore6APIGroup < Inferno::TestGroup
     title 'Single Patient API (US Core 6.1.0)'
     short_title 'Single Patient API'
     description %(
+      This scenario verifies the ability of a system to provide a 'Single Patient API'
+      as described in the (g)(10) Standardized API certification criterion.
+      Prior to running this scenario, systems must recieve a verified access token
+      from one of the previous SMART App Launch scenarios.
+
       For each of the relevant USCDI data elements provided in the
-      CapabilityStatement, this test executes the [required supported
+      CapabilityStatement, this scenario executes the [required supported
       searches](http://hl7.org/fhir/us/core/STU6.1/CapabilityStatement-us-core-server.html)
       as defined by the US Core Implementation Guide v6.1.0.
 

lib/onc_certification_g10_test_kit/smart_app_launch_invalid_aud_group.rb

@@ -8,26 +8,25 @@ class SMARTAppLaunchInvalidAudGroup < Inferno::TestGroup
       * Redirect URI: `#{SMARTAppLaunch::AppRedirectTest.config.options[:redirect_uri]}`
     )
     description %(
-      # Background
-
-      The Invalid AUD Sequence verifies that a SMART Launch Sequence,
-      specifically the Standalone Launch Sequence, does not work in the case
-      where the client sends an invalid FHIR server as the `aud` parameter
-      during launch. This must fail to ensure that a genuine bearer token is not
-      leaked to a counterfit resource server.
-
-      This test is not included as part of a regular SMART Launch Sequence
-      because it requires the browser of the user to be redirected to the
-      authorization service, and there is no expectation that the authorization
-      service redirects the user back to Inferno with an error message. The only
-      requirement is that Inferno is not granted a code to exchange for a valid
-      access token. Since this is a special case, it is tested independently in
-      a separate sequence.
+      This scenario verifies that a SMART Launch Sequence, specifically the
+      Standalone Launch Sequence, does not succeed in the case where the client
+      sends an invalid FHIR server as the `aud` parameter during launch. This
+      must fail to ensure that a genuine bearer token is not leaked to a
+      counterfit resource server.
+
+      This test is not included in earlier scenarios because it requires the
+      browser of the user to be redirected to the authorization service, and
+      there is no expectation that the authorization service redirects the user
+      back to Inferno with an error message. The only requirement is that
+      Inferno is not granted a code to exchange for a valid access token. Since
+      this is a special case, it is tested independently in a separate sequence.
 
       Note that this test will launch a new browser window. The user is required
       to 'Attest' in the Inferno user interface after the launch does not
       succeed, if the server does not return an error code.
 
+      The following implementation specifications are relevant to this scenario:
+
       * [Standalone Launch Sequence
         (STU1)](http://hl7.org/fhir/smart-app-launch/1.0.0/index.html#standalone-launch-sequence)
       * [Standalone Launch

lib/onc_certification_g10_test_kit/smart_asymmetric_launch_group.rb

@@ -6,8 +6,6 @@ class SMARTAsymmetricLaunchGroup < Inferno::TestGroup
     title 'Asymmetric Client Standalone Launch'
     short_title 'Asymmetric Client Launch'
     description %(
-      # Background
-
       The [Standalone
       Launch Sequence](http://hl7.org/fhir/smart-app-launch/STU2/app-launch.html#launch-app-standalone-launch)
       allows an app, like Inferno, to be launched independent of an
@@ -19,11 +17,10 @@ class SMARTAsymmetricLaunchGroup < Inferno::TestGroup
 
       These tests specifically verify a system's support for [confidential
       asymmetric client
-      authentication](https://hl7.org/fhir/smart-app-launch/STU2/client-confidential-asymmetric.html).
-
-      # Test Methodology
+      authentication](https://hl7.org/fhir/smart-app-launch/STU2/client-confidential-asymmetric.html),
+      which is not verified in earlier scenarios.
 
-      Inferno will redirect the user to the the authorization endpoint so that
+      In this scenario, Inferno will redirect the user to the the authorization endpoint so that
       they may provide any required credentials and authorize the application.
       Upon successful authorization, Inferno will exchange the authorization
       code provided for an access token.

lib/onc_certification_g10_test_kit/smart_ehr_patient_launch_group.rb

@@ -4,10 +4,10 @@ module ONCCertificationG10TestKit
   class SMARTEHRPatientLaunchGroup < SMARTAppLaunch::EHRLaunchGroup
     title 'EHR Launch with Patient Scopes'
     description %(
-      # Background
       Systems are required to support the `permission-patient` capability as
       part of the [Clinician Access for EHR Launch Capability
       Set.](http://hl7.org/fhir/smart-app-launch/1.0.0/conformance/index.html#clinician-access-for-ehr-launch)
+      Previous scenarios do not verify this specific combination of capabilies.
 
       Additionally, if an application launched from an EHR requests and is
       granted a clinical scope restricted to a single patient, the EHR SHALL
@@ -19,9 +19,7 @@ class SMARTEHRPatientLaunchGroup < SMARTAppLaunch::EHRLaunchGroup
       * Launch URI: `#{SMARTAppLaunch::AppLaunchTest.config.options[:launch_uri]}`
       * Redirect URI: `#{SMARTAppLaunch::AppRedirectTest.config.options[:redirect_uri]}`
 
-      # Test Methodology
-
-      Inferno will attempt an EHR Launch with a clinical scope restricted to a
+      In this scenario, Inferno will attempt an EHR Launch with a clinical scope restricted to a
       single patient and verify that a patient-level scope is granted and a
       patient id is received.
 

lib/onc_certification_g10_test_kit/smart_ehr_patient_launch_group_stu2.rb

@@ -4,10 +4,10 @@ module ONCCertificationG10TestKit
   class SMARTEHRPatientLaunchGroupSTU2 < SMARTAppLaunch::EHRLaunchGroupSTU2
     title 'EHR Launch with Patient Scopes'
     description %(
-      # Background
       Systems are required to support the `permission-patient` capability as
       part of the [Clinician Access for EHR Launch Capability
       Set.](http://hl7.org/fhir/smart-app-launch/STU2/conformance.html#clinician-access-for-ehr-launch)
+      Previous scenarios do not verify this specific combination of capabilies.
 
       Additionally, if an application launched from an EHR requests and is
       granted a clinical scope restricted to a single patient, the EHR SHALL
@@ -19,9 +19,7 @@ class SMARTEHRPatientLaunchGroupSTU2 < SMARTAppLaunch::EHRLaunchGroupSTU2
       * Launch URI: `#{SMARTAppLaunch::AppLaunchTest.config.options[:launch_uri]}`
       * Redirect URI: `#{SMARTAppLaunch::AppRedirectTest.config.options[:redirect_uri]}`
 
-      # Test Methodology
-
-      Inferno will attempt an EHR Launch with a clinical scope restricted to a
+      In this scenario, Inferno will attempt an EHR Launch with a clinical scope restricted to a
       single patient and verify that a patient-level scope is granted and a
       patient id is received.
 

lib/onc_certification_g10_test_kit/smart_ehr_practitioner_app_group.rb

@@ -26,19 +26,33 @@ class SmartEHRPractitionerAppGroup < Inferno::TestGroup
     )
 
     description %(
-      Demonstrate the ability to perform an EHR launch to a SMART on FHIR
+      This scenario verifies the ability of a system to perform a single EHR
+      Launch.  Specifically, this scenario performs an EHR launch to a SMART on FHIR
       confidential client with patient context, refresh token, OpenID Connect
       (OIDC) identity token, and (SMART v2 only) use the POST HTTP method for
-      code exchange. After launch, a simple Patient resource read is performed
-      on the patient in context. The access token is then refreshed, and the
-      Patient resource is read using the new access token to ensure that the
-      refresh was successful. Finally, the authentication information provided
-      by OpenID Connect is decoded and validated.
+      code exchange.
+
+      After launch, a simple Patient resource read is performed on the patient
+      in context. The access token is then refreshed, and the Patient resource
+      is read using the new access token to ensure that the refresh was
+      successful. Finally, the authentication information provided by OpenID
+      Connect is decoded and validated.
+
+      Prior to running this scenario, register Inferno as an EHR-launched confidential
+      client with the following information:
+
+      Prior to running this test, register Inferno as an EHR-launched
+      application using the following information:
+
+      * Launch URI: `#{SMARTAppLaunch::AppLaunchTest.config.options[:launch_uri]}`
+      * Redirect URI: `#{SMARTAppLaunch::AppRedirectTest.config.options[:redirect_uri]}`
 
       For EHRs that use Internet Explorer 11 to display embedded apps,
       please review [instructions on how to complete the EHR Practitioner App
       test](https://github.com/onc-healthit/onc-certification-g10-test-kit/wiki/Completing-EHR-Practitioner-App-test-in-Internet-Explorer/).
 
+      The following implementation specifications are relevant to this scenario:
+
       * [SMART on FHIR
         (STU1)](http://www.hl7.org/fhir/smart-app-launch/1.0.0/)
       * [SMART on FHIR