This library holds the test case definition files used when running automated testing against a number of the CCD backend microservices. This library is designed to be used with the BEFTA Framework, which can dynamically generate an environment specific version of these definition files and import them to a CCD Definition Store instance.

For information on prerequisites and how to configure a project to use these test definition files see BEFTA Framework.

This library contains definition files in both Excel and JSON formats.

Typically, CCD services under test will call BEFTA Framework code in order to load and import this definition data before running the functional tests.

graph LR
  env-var[Environment<br>Variables];
  def-store([CCD<BR>Definition<BR>Store]);
  elasticsearch([CCD<BR>Data Store<BR>Elasticsearch]);
  user-profile-store([CCD<BR>User Profile<BR>Store]);
  ccd-roles-json-->ccd-roles-list;
  json-->excel-generated;
  env-var-->excel-generated;
  ccd-roles-list-->|publish<BR>CCD roles|def-store;
  excel-generated-->|import<BR>definitions|def-store;
  def-store-->|publish<BR>data schema|elasticsearch;
  def-store-->|user profile<BR>defaults|user-profile-store;
  subgraph test-definitions[CCD Test Definitions]
    ccd-roles-json[CCD Roles<BR>JSON];
    excel[Templated<BR>Excel];
    json[Templated<BR>JSON];
    excel-->|definitionsToJson|json;
  end
  subgraph befta-fw[BEFTA Framework]
    ccd-roles-list[CCD Roles<BR>List];
    excel-generated[Generated<BR>Excel];
  end
  classDef plain fill:#ccc,stroke:#fff,stroke-width:4px,color:#000;
  classDef excel fill:#93c47d,stroke:#fff,stroke-width:4px,color:#fff;
  classDef json fill:#6fa8dc,stroke:#fff,stroke-width:4px,color:#fff;
  classDef library fill:#fff,stroke:#ccc,stroke-width:2px,color:#777;
  class def-store,user-profile-store,elasticsearch,env-var plain;
  class excel,excel-generated excel;
  class json,ccd-roles-json,ccd-roles-list json;
  class test-definitions,functional-test,befta-fw library;

(mermaid live edit)

The BEFTA Framework will by default load the JSON definitions from the resource directory uk/gov/hmcts/ccd/test_definitions/valid, and will combine them with Environment variables and flags to create the environment specific Excel files and import them to the CCD Definition Store.

This library contains a JSON file listing the CCD roles needed during the import of the test definition files. The DataLoaderToDefinitionStore class supplied by the BEFTA Framework will load CCD roles from a file named ccd-roles.json and will publish them to the CCD Definition Store prior to importing the generated definition files, see Importing CCD roles.

The following environment variables are used during the BEFTA import process to dynamically populate the templated callback URLs in the definition files:

Note: The BEFTA Framework may also attempt to rewrite some URLs to their environment specific namespaces, e.g. converting AAT URL -> Demo URL.

⚠️ Any changes made to Excel files in the directory src/main/resources/uk/gov/hmcts/ccd/test_definitions/excel will NOT be imported to the definition store.

The Excel files may be updated, rather than the JSON directly, but for these changes to take effect, they must be applied to the corresponding JSON files, by executing the DefinitionConverter class provided by BEFTA Framework. This can be done by either:

• Running DefinitionConverter against all Excel files

  The definitionsToJson gradle task will run the DefinitionConverter against each of the Excel files in the directory src/main/resources/uk/gov/hmcts/ccd/test_definitions/excel. This will replace the corresponding output in the following directory: src/main/resources/uk/gov/hmcts/ccd/test_definitions/valid.

    ./gradlew definitionsToJson

OR

• Running DefinitionConverter against a single file

  This can be done by creating a run configuration within your IDE, providing the path to the main class uk.gov.hmcts.befta.dse.ccd.DefinitionConverter, as well as the necessary program arguments listed below.

    arg1: to-json | to-excel : key word to convert from excel to json or from json to excel
    arg2: input file path for excel document or parent jurisdiction folder for json version
    arg3: (Optional) output folder path for resulting json or excel file. By default will use parent folder from the input location
    arg4: (Optional) Boolean: true - use jurisdiction name to generate the parent folder name when converting from excel to JSON,
          false - use file name as the folder name
  

The quickest way to populate a new/empty CCD-Docker environment with the test definition files is to run either the smoke or functional tests on either a local clone of CCD Definition Store or CCD Data Store:

• Running smoke tests

  ./gradlew smoke

OR

• Running functional tests

  ./gradlew functional

The Excel files in this library should not be imported directly into an environment as they contain callback URLs that are in a templated format: ${ENV_VAR:http:https://default.value}/rest_of_url_path. Without these URLs being correctly processed by the BEFTA Framework into valid values will result in any attempt to trigger the related case events to fail.

Note: Importing these raw Excel files into a higher-level environment may cause in-flight pipelines running against that environment to fail.

Therefor, to generate a set of definition files without the templated URLs: ensure the environment variables are set and then use the following command:

./gradlew definitionsToExcel

The generated Excel files will be outputted to the following directory: src/main/resources/uk/gov/hmcts/ccd/test_definitions/excel_generated.

Note: To import one of these generated definition files into a local CCD-Docker environment, see import case definition.

To test changes to these definition files locally before creating a pre-release version:

Changes in this project:

1. Update Excel files.
2. Re-generate the JSON files, execute:

   ./gradlew definitionsToJson

3. Update the build number in the build.gradle file to a unique pre-release build number in the format: <next-release-number>_<ticket-number>: e.g. 7.22.2_CCD-3853.
4. Publish library to local repository, execute:

   ./gradlew publishToMavenLocal

Testing in CCD Definition Store and / or CCD Data Store project:

5. Update the ccd-test-definitions version number in the project's build.gradle file:

   testCompile group: 'com.github.hmcts', name: 'ccd-test-definitions', version: '7.22.2_CCD-3853'

6. Run functional tests, execute:

   ./gradlew functional

The case definition import process includes data being published to each of the following services, see definition file generate & import process for diagram of process flow:

• CCD Definition Store,
• CCD Data Store's elasticsearch instance,
• CCD User Profile Service.

For the preview pipelines, by default, this will involve data being published to shared instances of these services. Therefor, to prevent unapproved case definition changes impacting other pipelines it is important that these changes are tested in isolation.

To run in isolation requires the generation of test pull requests (PRs) in each of the services: which have:

• keep-helm label set to ensure instance remains active after the pipeline is complete.
• Preview chart configuration updated so each service correctly references the other PR instances.
• Jenkins' configuration updated so any BEFTA steps can correctly reference the other PR instances.

The pipeline configuration is explained in further detail below for each service:

Note: the test pipelines/PRs should be generated and running in isolation in advance of their configuration to use the CCD Test Definition pre-release version that is under test.

CCD Definition Store pipeline configuration:

• charts/ccd-definition-store-api/values.preview.template.yaml override the following:
  • ELASTIC_SEARCH_HOST with CCD Data Store PR number.
  • USER_PROFILE_HOST with CCD User Profile Service PR number. (optional) Only required if User Profile Service is included in isolation.

CCD Data Store pipeline configuration:

• charts/ccd-data-store-api/values.preview.template.yaml override the following:
  • DEFINITION_STORE_HOST with CCD Definition Store PR number.
  • USER_PROFILE_HOST with CCD User Profile Service PR number. (optional) Only required if User Profile Service is included in isolation.
• Jenkinsfile_CNP override the following:
  • definitionStoreDevelopPr with CCD Definition Store PR number.
  • env.ELASTIC_SEARCH_FTA_ENABLED to "true". i.e. so functional tests include all Elasticsearch elements.

CCD User Profile Service pipeline configuration: (optional) Only required if testing changes for a new jurisdiction or if changing the user profile defaults in the UserProfile tab; as these will be published to the CCD User Profile Service.

• Jenkinsfile_CNP override the following:
  • definitionStoreDevelopPr with CCD Definition Store PR number.

Only once all of the above are up and running can they then have their ccd-test-definitions version number in the project's build.gradle file updated to point to the pre-release version that is under test:

testCompile group: 'com.github.hmcts', name: 'ccd-test-definitions', version: '7.22.2_CCD-3853'

This project is licensed under the MIT License - see the LICENSE file for details.