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;
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:
Name | Default (if not set) | Description |
---|---|---|
TEST_STUB_SERVICE_BASE_URL | http://ccd-test-stubs-service-aat.service.core-compute-aat.internal |
Path to hmcts/ccd-test-stubs-service instance. When running BEFTA import against a local CCD-Docker use http://host.docker.internal:5555 . |
MCA_API_BASE_URL | http://aac-manage-case-assignment-aat.service.core-compute-aat.internal |
Path to hmcts/aac-manage-case-assignment instance. When running BEFTA import against a local CCD-Docker/ACA-Docker use http://host.docker.internal:4454 . |
Note: The BEFTA Framework may also attempt to rewrite some URLs to their environment specific namespaces, e.g. converting AAT URL -> Demo URL.
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 filesThe
definitionsToJson
gradle task will run theDefinitionConverter
against each of the Excel files in the directorysrc/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 fileThis 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
Priming a new local CCD-Docker environment
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://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:
- Update Excel files.
- Re-generate the JSON files, execute:
./gradlew definitionsToJson
- 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
. - Publish library to local repository, execute:
./gradlew publishToMavenLocal
Testing in CCD Definition Store and / or CCD Data Store project:
- Update the
ccd-test-definitions
version number in the project'sbuild.gradle
file:testCompile group: 'com.github.hmcts', name: 'ccd-test-definitions', version: '7.22.2_CCD-3853'
- 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.