Gherkin Scenario drafting document
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.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.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.3.1 Config tests
- 2.4 Negative tests
- 3 Parking lot for potential future features/scenarios
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 createsConfiguration 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 instanceConfiguration 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 toConfiguration 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
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
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: Get Consent Agreement / Data Policy
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.
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
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
Remarks:
Important architectural consideration: How to orchestrate the whole workflow: from “ask for consent” to “get me the data as allowed by the consent” from the integrity and security point of view?
Current assumptions are that
there is a common trust framework (eg IM-BB) that validates legitimate request and workflow, so that the Application is previously known and authorised for transactions with Consent-BB
Consent-BB can independently verify the <ID> of the Individual (aka data subject)
Application is responsible for initiating/orchestrating the workflow within the above restrictions
Feature: Request audit trackers
Feature:
Negative tests
(TBD)
Parking lot for potential future features/scenarios
Feature: Sign consent Record as a Delegate