Gherkin Scenario drafting document

Owned by Benjamin Balder Bach
Last updated: Jul 07, 2023
9 min read

Proposed Workflow:

  1. Draft a feature + scenario(s) from GovStack Gherkin scenarios - user guide + template

  2. Discuss

  3. Move to GitHub for final discussion and implementation: https://github.com/GovStackWorkingGroup/bb-consent/tree/main/test/gherkin/features

  4. Reuse (or if needed update) the 3 Terminology | bb-consent

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

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

 

 

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