Expand

title	MENU

Table of Contents

style	none

1. Purpose

The purpose of the tool is to provide implementers with a reliable and efficient test tool for ensuring conformance to the Ozone Connect implementation within the API Hub. This tool aims to simplify the testing process, ensure adherence to standards, and enhance the overall quality and interoperability of implementations.

2. Scope

This manual covers the essential aspects of the Testing Tool, including its installation, usage, and testing capabilities. It provides detailed instructions and guidelines to help users effectively utilise the tool within their development and testing environments. The scope includes:

Installation and setup	Provides instructions for installing and setting up the Testing Tool using Docker, including prerequisites and initial configuration. This tool has been successfully tested on Ubuntu Linux and on MacOS.
Usage instructions	Details the commands and options available in the Testing Tool CLI tool, with examples for effective usage.
Testing	Explains the testing procedures and conformance checks, including how to run tests and interpret the results.

3. Audience

The primary audience for this manual includes developers, QA engineers, and technical implementers who are involved in the integration and testing of the Ozone Connect implementation for the API Hub.

This manual assumes that the audience has a basic understanding of CLI tools, Docker, CBUAE Open Finance Standards and Ozone Connect specifications.

4. Overview

The Testing Tool is a command-line interface (CLI) based testing tool designed to assist implementers in verifying their conformance to the Ozone Connect implementation. Developed specifically for the API Hub, the Testing Tool provides a comprehensive suite of tests that validate various aspects of the implementation against the predefined standard. The tool runs within a Docker container, ensuring a consistent and isolated testing environment. By using the Testing Tool, implementers can efficiently identify and rectify issues, ensuring that their implementations meet the required conformance criteria.

5. Setup Requirements

Before You Start:

Familiarise yourself with the Ozone Connect specifications.
Ensure you have https://www.docker.com/ installed locally on your machine to run Docker containers.

6. Usage

The instructions below are based on using the Testing Tool to test against the Ozone Connect v2024.34.00

Below is the command which runs the Testing Tool Docker container with the specified configuration and logging options for running some pre-defined tests against the mock Ozone Connect Server hosted in the cloud:

Code Block

#Sample command without any client configuration being provided
docker run --user root --rm -it \
-v "$(pwd)/logs:/usr/o3/tr-ozone-connect/logs" \
public.ecr.aws/g5c5c6i0/tr-image/tr-ozone-connect:cbuae-ais \
yarn tr-ozone-connect \
--formatter terse \
--loglevel-runner info \
--config /usr/o3/tr-ozone-connect/config/config.yaml \
--out /usr/o3/tr-ozone-connect/logs/test_logs.json \
--regex 'Id:[CT_A001]'

In order to run the tests against the LFI’s implementation of Ozone Connect the next command should be executed: (This command has the facility to add a custom configuration file.)

Line number 3 is newly added below.

Code Block

#Sample command WITH the client configuration being provided
docker run --user root --rm -it \
-v "$(pwd)/config:/usr/o3/tr-ozone-connect/config" \
-v "$(pwd)/logs:/usr/o3/tr-ozone-connect/logs" \
public.ecr.aws/g5c5c6i0/tr-image/tr-ozone-connect:cbuae-ais \
yarn tr-ozone-connect \
--formatter terse \
--loglevel-runner info \
--config /usr/o3/tr-ozone-connect/config/config.yaml \
--out /usr/o3/tr-ozone-connect/logs/test_logs.json \
--regex 'Id:[.*]'

The command provided above can be broken down into three main parts:

Running the Docker Container: The first part runs the Testing Tool Docker container, mounting the necessary directories and setting up the environment:

Option

Description

-v "$(pwd)/config:/usr/o3/tr-ozone-connect/config"

If the LFI configuration is not provided, the tool will attempt to connect to a the Ozone Connect mock server deployed by Ozone in the cloud. For detailed information on the configuration file format, please refer to the configuration file section: https://openfinanceuae.atlassian.net/wiki/spaces/APIHubDocsv5/pages/180782118/Testing+Tool+User+Guide#6.2-Configuration-File

SSL certificates are necessary for secure mTLS connection between the Testing Tool and LFI’s implementation of Ozone Connect. The method to generate these certificates is documented in the Certificates Generation section: https://openfinanceuae.atlassian.net/wiki/spaces/APIHubDocsv5/pages/180782118/Testing+Tool+User+Guide#6.3-Test-Certificates

After generating the certificates, copy them into a folder named config/certs on the host machine from where the test command will be executed. These copied files are then passed to the Docker container using the configuration options mentioned earlier.

-v "$(pwd)/logs:/usr/o3/tr-ozone-connect/logs"

This option is mandatory and needs to be passed to check the logs after the program has run. The logs will be available in this folder after the tests are run.

Acquiring the latest docker image:

Option	Description
`public.ecr.aws/g5c5c6i0/tr-image/tr-ozone-connect:cbuae-ais \`	This is the location of the publicly available Test Tool Docker image.

Executing the Ozone Testing Tool: This 3rd part executes the Ozone Testing Tool within the container with a set of specified options:

Code Block
yarn tr-ozone-connect \ --formatter terse \ --loglevel-runner info \ --config /usr/o3/tr-ozone-connect/config/config.yaml \ --out /usr/o3/tr-ozone-connect/logs/test_logs.json \ --regex 'Id:[CT_A001]'

In order to run the above command against LFI’s implementation of Ozone Connect, the LFI needs to:

Create a common configuration file.

6.1 Common Config Files Options

Create an input configuration file and put it in a ./config folder.
Acquire or generate the SSL certificates to connect to the Ozone Connect server.
Put the certificates in a ./config/certs folder.
Execute the command from the parent folder of ./config to run the tests.

For more details about the options in the configuration file, please review section the tablebelow.

Option	Description	Possible Values
-h, --help	Show help (boolean)
-c, --config	Input test configuration files in .yaml or .json format (Format : string, required)	config.yaml, config.json, ./config/config.yaml
-f, --folder	Preconfigured path to the folders with the test files (Format : string, required)	src/tests, tests, ./src/tests
-o, --out	Output file name (Format : string, optional)	results.json, output.json, ./test_output.json
-e, --formatter	Use a standard formatter for the output (Format : string, optional)	full, terse, medium, errors
-r, --regex	Provide a regular expression for running selected tests. (Format : string, required)	‘Id:[CT_A001]' 'Id:[CT_A001,CT_A002]' 'Id:[CT_A.]' 'Id:[CT_A.,CT_B.*]' Note there is no space after the comma which separates the regex. Also note that the complete expression is inside '’
-v, --loglevel-runner	Log level for the test runner (Format : string, optional)	debug, info, silent
-l, --loglevel-suite	Log level for the test suite (Format : string, optional)	info
--version	Show version number (boolean)

6.1.1 Configuration File

This section provides a detailed explanation of the configuration file fields used in the Testing Tool for Open Banking APIs.

A sample configuration file (config.yaml) is as follows :

Code Block

baseUrl: https://mock.rt-cbuae.rt.dev.ozoneapi.co.uk
psuIdentifier:
  userId: '10000100000000000000002'
aisBasePath: openbanking/v1/ais
pisBasePath: openbanking/v1/pis
headers:
  o3-provider-id: 'RTCBUAE'
  o3-aspsp-id: 'RTCBUAE'
  o3-caller-org-id: '000015000000000000000001'
  o3-caller-client-id: '65e64982-f080-4785-a887-816f5274ea7e'
  o3-caller-software-statement-id: '000016000000000000000004'
  o3-api-uri: 'open-banking/account-information/v1/accounts'
  o3-api-operation: 'GET'
  o3-consent-id: 'aac-6359d9-ab01458-c45a358cbf3230733'
  o3-caller-interaction-id: 'bf630602-b0a5-467e-abe8-5e350f11f092'
  o3-ozone-interaction-id: 'e2ff21ca-dd11-4c05-98ef-403dcc8e588d'
  o3-psu-identifier: 'eyJ1c2VySWQiOiIxMDAwMDEwMDAwMDAwMDAwMDAwMDAwMDIifQ=='
certs:
  transport:
    ca: '/usr/o3/tr-ozone-connect/config/ozone2021-ca.pem'
    certFileName: '/usr/o3/tr-ozone-connect/config/ozone-issued-transport-HQuZPIt3ipkh33Uxytox1E.pem'
    keyFileName: '/usr/o3/tr-ozone-connect/config/ozone-issued-transport-HQuZPIt3ipkh33Uxytox1E.key'
    
accounts:
  accountTypes:
    SampleAccount:
      accountIds: ['100004000000000000000002']
    Corporate_ChargeCard_Active:
      accountIds: ['100004000000000000000008']
      accountType: "Corporate"
      accountSubType: "ChargeCard"
      status: "Active"
    Corporate_Savings_Active:
      accountIds: ['100004000000000000000003']
      accountType: "Corporate"
      accountSubType: "Savings"
      status: "Active"

Configuration	Description
baseUrl	Description: The base URL for the API endpoints. Type: String Example Value: https://<Some URL>
psuIdentifier userId	Description: The user identifier (PSU ID) used in the context of AIS. Type: String Example Value: '10000100000000000000002'
aisBasePath	Description: The base path for the Bank Data Sharing endpoints. Type: String Example Value: openbanking/v1/ais
pisBasePath	Description: The base path for the Bank Service Initiation endpoints. Type: String Example Value: openbanking/v1/pis
headers o3-ozone-interaction-id	Description: A unique identifier for tracking interactions. Type: String Example Value: 'UUID'
headers o3-api-operation	Description: The HTTP method used for the API operation. Type: String Example Value: 'GET'
headers o3-aspsp-id	Description: The identifier of the LFI. Type: String Example Value: 'RTCBUAE'
headers o3-api-uri	Description: The URI for the specific API endpoint. Type: String Example Value: 'open-banking/account-information/v1/accounts'
headers o3-caller-org-id	Description: The organization ID of the API caller. Type: String Example Value: '000015000000000000000001'
headers o3-caller-client-id	Description: The client ID of the API caller. Type: String Example Value: 'UUID'
headers o3-caller-software-statement-id	Description: The software statement ID of the API caller. Type: String Example Value: '000016000000000000000004'
headers o3-consent-id	Description: The consent ID provided by the PSU. Type: String Example Value: 'UUID'
headers o3-psu-identifier	Description: The identifier for the PSU, typically a base64-encoded JSON object. Type: String Example Value: 'base64 encoded Json string'
headers o3-provider-id	Description: The identifier for the service provider. Type: String Example Value: 'RTCBUAE'
headers o3-caller-interaction-id	Description: A unique identifier for tracking caller interactions. Type: String Example Value: 'UUID'
certs transport ca	Description: Path to the CA certificate for transport layer security. Type: String Example Value: '/usr/o3/tr-ozone-connect/config/ozone2021-ca.pem'
certs transport certFileName	Description: Path to the transport layer certificate file. Type: String Example Value: '/usr/o3/tr-ozone-connect/config/ozone-issued-transport-HQuZPIt3ipkh33Uxytox1E.pem'
certs transport keyFileName	Description: Path to the private key file for the transport layer certificate. Type: String Example Value: '/usr/o3/tr-ozone-connect/config/ozone-issued-transport-HQuZPIt3ipkh33Uxytox1E.key'
accounts `accountTypes`	Description: A list of `accountToTest` key-value pairs which are internally used in the tests. Type: Array Example : Corporate_ChargeCard_Active Corporate_CreditCard_Dormant Retail_CurrentAccount_Active Retail_EMoney_Active AccountIdWithInValidBalanceType AccountIdWithCreditIndicatorRetail_CustomerType Corporate_CustomerType SME_CustomerType All the `accountToTest` are a crucial part of the test framework. To modify the parameters of a particular test we should know the `accountToTest` value of that test. Then check that `accountToTest` in the config.yaml file. And update it as per necessity. A list of all the `accountToTest` values can be found in: List of accountToTest values for the Ozone Connect Testing Tool

6.1.2 Test Certificates

The certificates in the certs folder are critical for securing communications between the LFI and the OFP using mTLS.

Below you can find a brief explanation of how you can generate test certificates in order to run the testing tool against your implementation.

Please keep in mind that you can also use certificates provided by OFTF. In this case please skip certificate generation step.

Steps to Generate Test Certificates:

Create a Certificate Authority (CA)
- A CA is responsible for signing certificates. If you do not have an existing CA, you can create one.
- Generate the private key for your CA:
  openssl genpkey -algorithm RSA -out ozone2021-ca.key -aes256
- Create a self-signed root certificate:
  openssl req -x509 -new -nodes -key ozone2021-ca.key -sha256 -days 365 -out ozone2021-ca.pem
Generate a Private Key for the Server
- Generate the private key for your server:
  openssl genpkey -algorithm RSA -out ozone-issued-transport.key -aes256
Create a Certificate Signing Request (CSR)
- Generate a CSR using the server's private key:
  openssl req -new -key ozone-issued-transport.key -out ozone-issued-transport.csr
Sign the CSR with Your CA
- Use your CA to sign the CSR, creating the server certificate:
  openssl x509 -req -in ozone-issued-transport.csr -CA ozone2021-ca.pem -CAkey ozone2021-ca.key -CAcreateserial -out ozone-issued-transport.pem -days 365 -sha256
Verify the Certificate
- Ensure the certificate is correctly generated and can be verified against the CA:
  openssl verify -CAfile ozone2021-ca.pem ozone-issued-transport.pem

Summary of Files

CA Certificate (ozone2021-ca.pem)
- The root certificate used to sign other certificates.
Server Private Key (ozone-issued-transport.key)
- The private key for the server, kept secure and not shared.
Server Certificate (ozone-issued-transport.pem)
- The public certificate signed by the CA, used for secure communications.

6.2 Test Input Configurations

In order to run the command with custom test data, the LFI needs to :

Create new test input configuration file/s with a name similar to the test suite and suffixed by .test.yaml
For example the test suite is : get-accounts, then the name of the test input configuration file will get-accounts.test.yaml
The name of the test suite can be found when we run the command and in the output we observe :
+ Running suite: get-accounts - AIS Endpoints
OR
get-accounts - 9/11 - AIS Endpoints
Currently there are 3 test suites added in the test tool.
1. get-accounts
2. get-transactions
3. get-payments
  So the LFI can create 3 such files and mount them to appropriate files inside the container.
  These files are already present inside the container. Mounting files from outside will override the files inside the container.
  So we can run the tests with either the default test data or with mount new test data.
The mount points for all the 3 files inside the container are as follows :
1. The mount point for get-accounts.test.yaml inside the container is /usr/o3/tr-ozone-connect/tests/data-sharing/get-accounts.test.yaml
2. The mount point for get-transactions.test.yaml inside the container is /usr/o3/tr-ozone-connect/tests/data-sharing/get-transactions.test.yaml
3. The mount point for get-payments.test.yaml inside the container is /usr/o3/tr-ozone-connect/tests/service-initiaiton/get-payments.test.yaml
We mount these files inside the container using the command line argument “-v”
Example : -v "$(pwd)/get-accounts.test.yaml:/usr/o3/tr-ozone-connect/tests/data-sharing/get-accounts.test.yaml" \

6.2.1 Sample Test Input Configuration Files

6.2.1.a get-accounts.test.yaml

Code Block

tests:
  CT_1001:
    testName: "Succeeds if all headers are valid"
    testDescription: "If all headers are valid, the API must return a 200 and a record for each specified account id"
    accountIds: ["100004000000000000000001"]
    expectedStatus: 200
    accountSubType: "CurrentAccount"
    accountType: "Retail"
    status: "Active"

  CT_1002:
    testName: "Fails if o3-aspsp-id is not specified"
    testDescription: "If o3-aspsp-id is not specified, the API must return a 400 and an error body"
    accountIds: ["100004000000000000000001"]
    expectedStatus: 400
    suppressHeaders: ["o3-aspsp-id"]

  CT_1003:
    testName: "Fails if o3-aspsp-id has an invalid value"
    testDescription: "If o3-aspsp-id has an invalid value, the API must return a 200 and an error body"
    accountIds: ["100004000000000000000001"]
    expectedStatus: 200
    headers:
      o3-aspsp-id: "invalid-aspsp-id"

  CT_1004:
    testName: "Fails if o3-psu-identifier is not specified"
    testDescription: "If o3-psu-identifier is not specified, the API must return a 400 and an error body"
    accountIds: ["100004000000000000000001"]
    expectedStatus: 400
    suppressHeaders: ["o3-psu-identifier"]

  CT_1005:
    testName: "Fails if o3-psu-identifier is not b64 encoded"
    testDescription: "If o3-psu-identifier is not b64 encoded, the API must return a 400 and an error body"
    accountIds: ["100004000000000000000001"]
    expectedStatus: 400
    headers:
      o3-psu-identifier: "invalid-psu-identifier"

  CT_1006:
    testName: "Fails if o3-psu-identifier does not evaluate to a json structure"
    testDescription: "If o3-psu-identifier does not evaluate to a json structure, the API must return a 400 and an error body"
    accountIds: ["100004000000000000000001"]
    expectedStatus: 400
    headers:
      o3-psu-identifier: "aW52YWxpZC1wc3UtaWRlbnRpZmllcg==" # Evaluates to invalid-psu-identifier


  CT_1007:
    testName: "Fails if o3-psu-identifier does not contain userId"
    testDescription: "If o3-psu-identifier does not contain userId, the API must return a 400 and an error body"
    accountIds: ["100004000000000000000001"]
    expectedStatus: 400
    headers:
      o3-psu-identifier: "eyJmb28iOiJiYXIifQ==" # EValuates to {"foo":"bar"}

  CT_1008:
    testName: "Fails if accountIds query parameter is missing"
    testDescription: "If accountIds query parameter is missing, the API must return a 400 and an error body"
    expectedStatus: 400

  CT_1009:
    testName: "Succeeds if no valid accounts are specified"
    testDescription: "If no valid accounts are specified, the API must return a 200 and an empty data array"
    accountIds: ["0123456789"]
    expectedStatus: 200

  CT_1010:
    testName: "Fails if o3-ozone-interaction-id is not specified"
    testDescription: "If o3-ozone-interaction-id is not specified, the API must return a 400 and an error body"
    accountIds: ["100004000000000000000001"]
    expectedStatus: 400
    suppressHeaders: ["o3-ozone-interaction-id"]

  CT_1011:
    testName: "Fails if o3-api-operation is not specified"
    testDescription: "If o3-api-operation is not specified, the API must return a 400 and an error body"
    accountIds: ["100004000000000000000001"]
    expectedStatus: 400
    suppressHeaders: ["o3-api-operation"]

6.2.1.b get-transactions.test.yaml

Code Block

tests:
  CT_1101:
    testName: "Succeeds if valid accountId in path parameter returns transactions"
    testDescription: "Valid accountId provided in the path parameter should return a 200 and the accountId must be present in the response with a list of transactions"
    accountIds: ["100004000000000000000001"]
    expectedStatus: 200

6.2.1.c get-payments.test.yaml

Code Block

tests:
  CT_1201:
    testName: "Succeeds if valid paymentId in path parameter returns payments"
    testDescription: "Valid paymentId provided in the path parameter should return a 200 and the paymentId must be present in the response"
    paymentIds: ['abcdef1234567890']
    expectedStatus: 200

6.3 Configuration Description

Configuration	Description
tests	All the tests should follow after this section. The tests are identified using a testId.
`testId`	This is a test Id. Can be anything. Exmaple `CT_1201`
testId: `testName`	Description: A name for the test. Type: String
testId: `testDescription`	Description: Description for the test. Type: String
testId `accountIds`	Description: Type: Array Example Value: ['100004000000000000000001']
testId: `paymentIds`	Description: Type: Array Example Value: ['123456']
testId: `expectedStatus`	Description: A list of payment IDs used for testing payment-related endpoints. Type: String Example Value: `400`
testId `headers`	Description: A set of key value pair which will have a specific header as a key and its desired value. Type: Dictionary Example Value: `o3-aspsp-id: "invalid-aspsp-id"`
testId `suppressedHeaders`	Description: A list of headers to not include in the input. Type: Array. Example Value: `["o3-ozone-interaction-id"]`

7. Running Testing Tool

Follow the instructions below to run the Testing Tool:

Step 1

Create an input test configuration file and set up it in /config folder.

Please follow the Configuration File section in order to generate the required file: https://openfinanceuae.atlassian.net/wiki/spaces/APIHubDocsv5/pages/180782118/Testing+Tool+User+Guide#6.2-Configuration-File

Step 2

Acquire/Generate the SSL certificates and put them in a /config/certs folder.

Please follow the Test Certificates section in case you need to generate test certificates: https://openfinanceuae.atlassian.net/wiki/spaces/APIHubDocsv5/pages/180782118/Testing+Tool+User+Guide#6.3-Test-Certificates

Otherwise please use OFTF Certificates.

Step 3

Execute the testing tool command.

Code Block

#Sample command WITH the client configuration and custom tests being provided :

docker run --user root --rm -it \
-v "$(pwd)/config:/usr/o3/tr-ozone-connect/config" \
-v "$(pwd)/logs:/usr/o3/tr-ozone-connect/logs" \
-v "$(pwd)/get-accounts.test.yaml:/usr/o3public.ecr.aws/g5c5c6i0/tr-image/tr-ozone-connect/tests/data-sharing/get-accounts.test.yaml":cbuae-ais \
-v "$(pwd)/get-payments.test.yaml:/usr/o3/yarn tr-ozone-connect/tests/service-initiation/get-payments.test.yaml" \
-v "$(pwd)/get-transactions.test.yaml:/usr/o3/tr-ozone-connect/tests/data-sharing/get-transactions.test.yaml" \
public.ecr.aws/g5c5c6i0/tr-image/tr-ozone-connect:cbuae \
yarn tr-ozone-connect \
 \
--formatter terse \
--loglevel-runner info \
--config /usr/o3/tr-ozone-connect/config/config.yaml \
--out /usr/o3/tr-ozone-connect/logs/test_logs.json \
--regex 'Id:[.*]'

Step 4

The final section of the sample output, after all tests have been run and logs have been printed, will appear as follows.

Step 5 (optional)

Review the Testing Tool output log file containing the test case results. The log file's name is specified in the last part of the command in step 1 above. You can change this name each time you run the command. If not changed, successive runs will overwrite the same file.

Use any text editor to view the file :
vim $(pwd)/logs/test_logs.json

Step 6

The result of the test run are also available in an html file with similar name as the above file. This is present in the same folder as the above test_logs.json file.

Use any browser to open the html report file :
$(pwd)/logs/test_logs.html
A sample html report file can be found in:

View file

name	demo-test_logs.html

8. Test Cases

The list of supported test cases is available in the following document: Ozone Connect Test

9. Recorded Demonstration of using this tool

TestToolVersion3.mp4

Version	Old Version 2	New Version 3
Changes made by	Isla Humphreys	Isla Humphreys
Saved on	27 Sept 2024	27 Sept 2024

QA engineers	Professionals responsible for ensuring the quality and reliability of the Ozone Connect implementation by conducting thorough testing and identifying defects.
Integration Specialists	Experts focused on integrating and aligning the Ozone Connect implementation with the API Hub to ensure seamless interoperability and conformance.

Page Comparison

Versions Compared

Key

1. Purpose

2. Scope

3. Audience

4. Overview

5. Setup Requirements

6. Usage

6.1 Common Config Files Options

6.1.1 Configuration File

6.1.2 Test Certificates

6.2 Test Input Configurations

6.2.1 Sample Test Input Configuration Files

6.2.1.a get-accounts.test.yaml

6.2.1.b get-transactions.test.yaml

6.2.1.c get-payments.test.yaml

6.3 Configuration Description

7. Running Testing Tool

8. Test Cases

9. Recorded Demonstration of using this tool