Proposed Workflow:

Draft a feature + scenario(s) from GovStack Gherkin scenarios - user guide + template
Discuss
Move to GitHub for final discussion and implementation: https://github.com/GovStackWorkingGroup/bb-consent/tree/main/test/gherkin/features
Reuse (or if needed update) the https://govstack.gitbook.io/bb-consent/3-terminology

Important notes:

Everything should be aligned with a use case, however the feature and scenario should be generic
Use cases are referenced as a description of the feature
Scenarios only relate to BB via APIs

Contents

1 Reference example
2 Major themes
- 2.1 Newly identified roles
- 2.2 Smoke tests
  - 2.2.1 These tests now live here:
- 2.3 Positive tests (Happy Path)
  - 2.3.1 Config tests
    - 2.3.1.1 Policy CRUD
  - 2.3.2 Basic consent service flow scenarios
    - 2.3.2.1 Feature: Create an Individual in the Consent BB
    - 2.3.2.2 Feature: An Application can register and reference an Individual in the Consent BB
  - 2.3.3 Feature: Get Consent Agreement / Data Policy
  - 2.3.4 Feature: Sign Consent Record
  - 2.3.5 Feature: Verify Consent Record
  - 2.3.6 Feature: Request audit trackers
  - 2.3.7 Feature:
- 2.4 Negative tests
3 Parking lot for potential future features/scenarios
- 3.1 Feature: Sign consent Record as a Delegate

Reference example

We’ll keep this example updated to the latest perception of how a good scenario should be written.

Given a Configuration Administrator this creates Configuration Administrator in the database, the fixture is defined in the implementation. If the test relies on specific properties, they should be expressed in the scenario. For instance Configuration Administrator with name "Acme Corp".
And an Example Agreement for Configuration Administrator is an object that will exist in the database. It is implemented such that it belongs to Configuration Administrator.
When I fetch Example Agreement is an API call that fetches the Example Agreement fixture by its ID. The ID is irrelevant in the test, it is known by the implementation.
Then I get a valid Agreement with properties matching Example Agreement is the response of the API call validated according to some implementation (the validity should be elaborated but it’s the data structure here that’s in focus).

@method=GET @endpoint=/api/config/agreement/{agreementId}/
Feature: Consent Agreements can be fetched in a variety of scenarios.

  Reference: UC-Post-Partum-001
  
  Scenario: As the Configuration Administrator,
    my application has read access for its own Agreements
  
    This generic scenario implements UC-Post-Partum-001.
  
    Given a Configuration Administrator
    And an Example Agreement for Configuration Administrator
    When I fetch Example Agreement
    Then I get a valid Agreement with properties matching Example Agreement

Major themes

Newly identified roles

Configuration Administrator: a user with access to read/write configuration data in the API.

Smoke tests

These tests now live here: https://github.com/GovStackWorkingGroup/bb-consent/pull/41

Positive tests (Happy Path)

A “positive test” is used to verify the presence of a feature. Most tests will land here.

Config tests

Policy CRUD

The Policy object is the most basic object that may be referenced by Agreements. Agreements can reference Consent Records.

Open questions: Do we want to say “data controller” or “organization owner”? → Configuration Administrator

@method=GET @endpoint=/config/policy/{policyId}/

Feature: A Configuration Administrator can perform basic CRUDL operations on Policies

  Note: The Consent BB is not currently aware of users and permissions.
  Therefore, all tests should contain stub implementations for users and access.

@unit @positive
Scenario: A Configuration Administrator of an Organization can read a Policy.

  This generic scenario implements UC-C-PIC-A-003.

  Given an organization admin user with access to read configuration
    And an Example Policy for Test Organization exists
  When The User fetches Example Policy for Test Organization
  Then Example Policy for Test Organization is returned

@method=POST @endpoint=/config/policy/

Feature: A Configuration Administrator can perform basic CRUDL operations on Policies

  Note: The Consent BB is not currently aware of users and permissions.
  Therefore, all tests should contain stub implementations for users and access.

@unit @positive
Scenario: A Configuration Administrator of an Organization can create a Policy.

  This generic scenario implements UC-C-PIC-A-001.

  Given a Configuration Administrator user with access to modify configuration
  When The User creates an Example Policy for Test Organization
  Then a successful response is returned

@method=PUT @endpoint=/config/policy/{policyId}/

Feature: A Configuration Administrator can perform basic CRUDL operations on Policies

  Note: The Consent BB is not currently aware of users and permissions.
  Therefore, all tests should contain stub implementations for users and access.

@unit @positive
Scenario: A Configuration Administrator of an Organization can create a Policy.

  This generic scenario implements UC-C-PIC-A-001.

  Given a Configuration Administrator user with access to modify configuration
    And an Example Policy for Test Organization exists
  When the Version of the Policy is updated to 1.1
  Then the Version field of the Policy is 1.1 and all other fields are unchanged

@method=DELETE @endpoint=/config/policy/{policyId}/

Feature: A Configuration Administrator can perform basic CRUDL operations on Policies

  Note: The Consent BB is not currently aware of users and permissions.
  Therefore, all tests should contain stub implementations for users and access.

@unit @positive
Scenario: A Configuration Administrator of an Organization can delete an unused Policy

  This generic scenario implements UC-C-PIC-A-001.

  Given a Configuration Administrator user with access to modify configuration
    And an Example Policy for Test Organization exists
    And the Example Policy has no Agreements referencing it
  When the Policy is deleted
  Then reading the Policy returns an error

@method=GET @endpoint=/config/policies/

Feature: A Configuration Administrator can perform basic CRUDL operations on Policies

  Note: The Consent BB is not currently aware of users and permissions.
  Therefore, all tests should contain stub implementations for users and access.

@unit @positive
Scenario: A Configuration Administrator of an Organization can list all existing Policies

  This generic scenario implements UC-C-PIC-A-001.

  Given a Configuration Administrator user with access to read configuration
    And an Example Policy for Test Organization exists
    And an Second Example Policy for Test Organization exists
  When all policies are fetched
  Then both Example Policy for Test Organization exists and Second Example Policy for Test Organization exists are returned

Basic consent service flow scenarios

Use-case may be for example Registration for Postpartum Mother and Child Care Program (MCC)

Feature: Create an Individual in the Consent BB

Feature: Create an Individual in the Consent BB

  This feature is hypothetical in terms of use-case, as we are not yet
  covering registering directly with the Consent BB, registration is handled
  by other BBs ad-hoc.
  
  Reference: UC-Post-Partum-001

Scenario: Creating a new Individual for the first time

  Another Building Block or application can store a record of an individual
  for later reference. After creation, the Individual object has been stored
  permanently within Consent-BB.

  Given the Individual <functional/consent-ID> does not exist in the Consent BB
  When Application sends request to retrieve Consent Agreement for signing by the Individual <functional/Application-ID>
  Then Consent BB creates new Individual <functional/consent-ID> in its registry

Remarks: It is assumed above, that

the Individual <ID> is effectively a “functional ID used by Consent-BB” only (“Consent <ID>”), yet linked to a unique foundational identity that has been matched by an external ID service (eg IDV-BB), so that any Consent Record by could always be linked to the same Individual.
there is a back-end API connecting Consent-BB with IDV-BB to verify the matching pairs of
- Foundational <ID> & Consent <ID>
- Foundational <ID> & Application <ID>
there is agreement and (technical implementation) across the ecosystem, how ID-matching is done between the three autonomous agents: the Application, IDV-BB, Consent-BB

Feature: An Application can register and reference an Individual in the Consent BB

Feature: An Application can register and reference an Individual in the Consent BB

  Note on general registration:
  This feature is hypothetical in terms of use-case, as we are not yet
  covering registering directly with the Consent BB, registration is handled
  by other BBs ad-hoc.
  
  Reference: UC-Post-Partum-001

Scenario: An Application creates a new Individual

  Another Building Block or application can store a record of an individual
  for later reference. After creation, the Individual object has been stored
  permanently within Consent-BB.

  Given there are no Individuals registered
  When the Application registers Maryam with functional ID "1234"
  Then the Application receives a response containing a new Individual ID
    And there exists exactly one Individual ID with external reference "1234"

Feature: Get Consent Agreement / Data Policy

Feature: Get Consent Agreement

  Reference: UC-Post-Partum-001

Scenario: Application retrieves the Consent Agreement intended for signing

  Given an Agreement for the use-case exists in Consent BB
  When Application fetches a Consent Agreement for signing
  Then the Application gets a gets a draft Consent Record and  draft Signature objects for a given agreementId.

Remark: During service flow use-cases the Consent Agreement can be retrieved only for a concrete Individual for signing. To read a Consent Agreement without linking it to a specific Individual see configuration scenarios.

Feature: Get Data Policy for a Consent Agreement

  Reference: UC-Post-Partum-001

Scenario: Application retrieves Data Policy for the Consent Agreement

  Given an Agreement for the use-case exists in Consent BB
  When the Application requests the Data Policy 
    associated with the Agreement of the use-case
  Then the Application gets a valid Consent Policy

Remark: Every Consent Agreement has a related Data Policy, but the latter can apply to more than one Consent Agreement. Consent Agreements are defined by specific use-cases. Data policy can also change independently from the Consent Agreement - this is managed via configuration use-cases.

Feature: Sign Consent Record

Feature: Sign Consent Record

Background:
  Given Application has the Consent Agreement associated with Individual <ID>
    And Consent BB has Individual <ID> registered
    And Consent-BB can independently verify Individual <ID> based request by Application
    And Application has Individual <ID> and authentication token for the registration session 
    And Individual has read the Consent Agreement
    And Individual approves to sign Consent Agreement

Scenario: Sign Consent Record on Paper
  Given Application has captured the signature consent in a digital form (for example: scan of a paper form)
    And Application has necessary data for Draft Consent Agreement associated with Individual's <ID> and associated purpose within Data Policy
  When Application sends digital Consent Record payload with signature data to Consent BB
  Then Consent BB stores Consent Record associated with Individual <ID>
    And Consent BB sends confirmation to Application that Consent Record for Individual has been successfully signed
    
Scenario: Sign Consent Record Digitally
  Given Individual has capability to sign Consent Record digitally
  And Application has Draft Consent Agreement associated with Individual's <ID>
  When the Application sends digital Consent Record payload to Consent BB
  Then Consent BB obtaines digital signature from ID-BB for Consent Record associated with Individual <ID>
    And ID-BB sends signed Consent Record
    And ID-BB sends confirmation to Application that Consent Record for Individual has been successfully signed

Remarks:

Must be agreed, if Consent-BB accepts (any) signature from outside source (eg Application) or is independently controlling (eg initiating … accepting) the signing workflow (2023-03-06: Added for a future meeting)
the Individual <ID> is effectively a “functional ID used by Consent-BB” only (“Consent <ID>”), yet linked to a unique foundational identity that has been matched by an external ID service (eg IDV-BB), so that any Consent Record by could always be linked to the same Individual.
there is a back-end API connecting Consent-BB with IDV-BB to verify the matching pairs of
- Foundational <ID> & Consent <ID>
- Foundational <ID> & Application <ID>
there is agreement and (technical implementation) across the ecosystem, how ID-matching is done between the three autonomous agents: the Application, IDV-BB, Consent-BB

Feature: Verify Consent Record

Feature: Verify Consent Record

  Application verifies if Individual has signed Consent Record to fetch the
  needed Personal Data from Data Provider for use by Application according to
  the purpose in Data Policy
  
  Reference: UC-Post-Partum-001

Background:
  Given Consent-BB can independently verify Individual <ID> based request by
  Application

Scenario: Retrieve valid Consent Record 
  Given Individual has the Consent Record stored in Consent-BB 
  When Application requests from Consent-BB a specific Consent Record by
    an Individual <ID>
  Then Consent-BB sends ConsentAgreementID of valid ConsentRecord to Application
  
Scenario: Get response that no valid Consent Record exist
  Given Consent-BB has not stored the Consent Record by the Individual
  When Application requests from Consent-BB a specific Consent Record by 
    an Individual <ID>
  Then Consent-BB sends "Not found" as a response to Application