ml-testing-toolkit 18.13.0

package/documents/RULES_ENGINE.md

@@ -0,0 +1,403 @@
+Rules Engine
+============
+
+Table of Contents
+=================
+
+  - [Json Rules Engine:](#json-rules-engine)
+  - [Implementation in Self Testing Toolkit](#implementation-in-self-testing-toolkit)
+    - [Rules File](#rules-file)
+    - [Defining Conditions](#defining-conditions)
+    - [Events](#events)
+      - [FIXED_ERROR_CALLBACK and FIXED_CALLBACK](#fixed_error_callback-and-fixed_callback)
+      - [Configurable parameters](#configurable-parameters)
+      - [MOCK_ERROR_CALLBACK and MOCK_CALLBACK](#mock_error_callback-and-mock_callback)
+    - [Priority of rules](#priority-of-rules)
+
+This Self Testing Toolkit implemented "Rules Engine" by taking advantage of ***Json Rules Engine***.
+
+## Json Rules Engine:
+*"Json Rules Engine"* is a powerful, lightweight rules engine. Rules are composed of simple json structures, making them human readable and easy to persist.
+
+Rules are composed of two components: conditions and events. Conditions are a set of requirements that must be met to trigger the rule's event.
+
+You can refer https://www.npmjs.com/package/json-rules-engine for further information on JRE.
+
+## Implementation in Self Testing Toolkit
+
+The rules in self testing toolkit are implemented at two levels.
+* One for validating the incoming request and send error callback if the validation rule matches.
+* Another for generating callbacks if the callback rule matches.
+
+In both cases the conditions syntax is same as per the Json Rules Engine, where as the event types will be different for the two levels.
+
+### Rules File
+The rules file is a json file with an array of individual rules.
+
+A typical validation rule file syntax is like below.
+```
+[
+  {
+    "ruleId": 1,
+    "description": "If the transfer amount is equal to 2 USD, send a fixed error callback",
+    "conditions": {
+      "all": [
+        {
+          "fact": "path",
+          "operator": "equal",
+          "value": "/transfers"
+        },
+        {
+          "fact": "method",
+          "operator": "equal",
+          "value": "post"
+        },
+        {
+          "fact": "body",
+          "operator": "equal",
+          "value": "2",
+          "path": "amount.amount"
+        }
+      ]
+    },
+    "event": {
+      "type": "FIXED_ERROR_CALLBACK",
+      "params": {
+        "path": "/transfers/{$request.body.transferId}/error",
+        "method": "put",
+        "headers": {},
+        "delay": 100,
+        "body": {
+          "errorInformation": {
+            "errorCode": "5001",
+            "errorDescription": "The amount is less than the required amount"
+          }
+        }
+      }
+    }
+  }
+]
+```
+
+### Defining Conditions
+
+Conditions can be defined with either "all" or "any" type of arrays. In each array there are objects containing three basic properties "fact", "operator" and "value".
+
+  * Fact - facts are the variable names that can be one of the following
+    * path - The request path
+
+      Example: /transfers, /parties/MSISDN/9876543210 ... etc
+
+    * method - The http method of the request in lowercase
+
+      Example: get, post ... etc
+
+    * body - The request body object. The properties of the body can be specified using a *condition helper* called **"path"**.
+
+      Example: amount.amount from the body '{ "amount": { "amount": 20, "type": "USD" } }' can be compared with the following condition
+      ```
+      {
+        "fact": "body",
+        "operator": "equal",
+        "value": "100",
+        "path": "amount.amount"
+      }
+      ```
+
+    * pathParams - By using this the path parameter values from the request can be compared.
+
+      Example: Type & ID of pathParams from the get request /parties/{Type}/{ID}
+
+    * queryParams - By using this the query parameter values from the request can be compared.
+
+      Example: 'state' of queryParams from the get request /settlementWindows?state=OPEN
+
+    * operationPath - This is used for matching the path syntax from open API file
+
+      Example: operationPath contains the value /parties/{Type}/{ID} instead of /parties/MSISDN/9876543210 which can actually be found in the fact 'path'.
+
+  * Operator - The ```operator``` compares the value returned by the ```fact``` to what is stored in the ```value``` property.  If the result is truthy, the condition passes.
+    There are number of operators available to compare the values
+
+    * String and Numeric operators:
+
+      ```equal``` - _fact_ must equal _value_
+
+      ```notEqual```  - _fact_ must not equal _value_
+
+      _these operators use strict equality (===) and inequality (!==)_
+
+    * Numeric operators:
+
+      ```lessThan``` - _fact_ must be less than _value_
+
+      ```lessThanInclusive```- _fact_ must be less than or equal to _value_
+
+      ```greaterThan``` - _fact_ must be greater than _value_
+
+      ```greaterThanInclusive```- _fact_ must be greater than or equal to _value_
+
+    * String Numeric operators:
+
+      *(These operators can be used if the type fo the property is string, but we want to parse it to integer and compare)*
+
+      ```numericEqual``` - _fact_ must equal _value_
+      ```numericNotEqual``` - _fact_ must not equal _value_
+      ```numericLessThan``` - _fact_ must be less than _value_
+
+      ```numericLessThanInclusive```- _fact_ must be less than or equal to _value_
+
+      ```numericGreaterThan``` - _fact_ must be greater than _value_
+
+      ```numericGreaterThanInclusive```- _fact_ must be greater than or equal to _value_
+
+    * Array operators:
+
+      ```in```  - _fact_ must be included in _value_ (an array)
+
+      ```notIn```  - _fact_ must not be included in _value_ (an array)
+
+      ```contains```  - _fact_ (an array) must include _value_
+
+      ```doesNotContain```  - _fact_ (an array) must not include _value_
+  * Value - The actual value to compare
+
+  Following are the examples of conditions
+
+  ```
+  "all": [
+      {
+        "fact": "path",
+        "operator": "equal",
+        "value": "/transfers"
+      },
+      {
+        "fact": "method",
+        "operator": "equal",
+        "value": "post"
+      }
+  ]
+  ```
+
+  ```
+  "any": [
+      {
+        "fact": "body",
+        "path": "amount.type",
+        "operator": "equal",
+        "value": "GBP"
+      },
+      {
+        "fact": "body",
+        "path": "amount.type",
+        "operator": "equal",
+        "value": "USD"
+      }
+  ]
+  ```
+
+### Events
+
+And event can be defined with "type" and "params" properties.
+
+There are different type of events based on the rules engine level.
+
+* Validation Rules Engine
+  * FIXED_ERROR_CALLBACK
+  * MOCK_ERROR_CALLBACK
+  * NO_CALLBACK
+* Callbacks Rules Engine
+  * FIXED_CALLBACK
+  * MOCK_CALLBACK
+  * NO_CALLBACK
+* Synchronous Response Rules Engine
+  * FIXED_RESPONSE
+  * MOCK_RESPONSE
+
+#### FIXED_ERROR_CALLBACK and FIXED_CALLBACK
+
+For FIXED_ERROR_CALLBACK & FIXED_CALLBACK, we need to supply every detail for sending callback like path, method, headers & body
+Let's look at an example of an event type *FIXED_ERROR_CALLBACK*
+```
+"event": {
+  "type": "FIXED_ERROR_CALLBACK",
+  "params": {
+    "path": "/parties/{$request.params.Type}/{$request.params.ID}/error",
+    "method": "put",
+    "headers": {},
+    "delay": 100,
+    "body": {
+      "errorInformation": {
+        "errorCode": "5001",
+        "errorDescription": "The party {$request.params.ID} is not found"
+      }
+    }
+  }
+}
+```
+
+#### Configurable parameters
+
+You can observe the configurable parameters '\{\$request.params.Type\}' and '\{\$request.params.ID\}'. These values will be replaced with the values from the request in run time.
+
+The following is the list of configurable parameters that you can define anywhere in path, headers & body values.
+* $request.params - Parameters in the request path
+* $request.body - Request body
+* $request.path - Entire request path
+* $request.query - Query parameters of the request
+* $request.headers - Http headers of the request
+* $config.<param_name> - Configuration parameter value from environment or local.env file
+* $session.negotiatedContentType - Negotiated content type. Can be sent to callbacks and error callbacks
+* $session.uniqueId - UniqueID for the request session
+
+
+**Advanced parameters for developers:**
+
+There are some advanced parameters type *$function* is implemented for advanced users / developers. The syntax is like below
+
+* $function.sample.getSampleText (For development purpose)
+
+The above parameter calls the function 'getSampleText' in 'sample.js' file located at 'lib/mocking/custom-functions' folder. An argument will be passed to this function from which the developer can get the request parameters to process like 'arg1.request.body.quoteId', 'arg1.request.headers.date' ...etc
+
+Please be noted that these javascript files can not be change in runtime and need compilation for the changes.
+
+
+#### MOCK_ERROR_CALLBACK and MOCK_CALLBACK
+
+For MOCK_ERROR_CALLBACK & MOCK_CALLBACK, we don't need to supply the details like path, method, headers & body. The toolkit will generate the callback based on the openAPI definition file.
+
+Let's look at an example of an event type *MOCK_ERROR_CALLBACK*
+```
+"event": {
+  "type": "MOCK_ERROR_CALLBACK",
+  "params": {
+  }
+}
+```
+
+That's it, the self testing toolkit can be able to generate a mock callback based on the open API file with random values.
+
+**Also you can define the params like in fixed callbacks to override a particular value.**
+
+See the following example in which the generated values of the firstName & name will be replaced accordingly
+
+```
+"event": {
+  "type": "MOCK_CALLBACK",
+  "params": {
+    "body": {
+      "party": {
+        "personalInfo": {
+          "complexName": {
+            "firstName": "A fixed value",
+          }
+        }
+        "name": "The party with phone number ${request.params.ID}"
+      }
+    }
+  }
+}
+
+```
+
+#### NO_CALLBACK
+
+For NO_CALLBACK, there are some test cases where the requirements dictate that there is no follow up callback.
+
+```
+"event": {
+  "type": "NO_CALLBACK",
+}
+```
+
+#### MOCK_RESPONSE and FIXED_RESPONSE
+
+These event types are used for defining events for synchronous response rules.
+
+These are same like callback event types, but the only difference is we need to provide the statusCode for FIXED_RESPONSE type. MOCK_RESPONSE automatically picks up the success response code from api specification file.
+
+Let's look at an example of an event type *FIXED_RESPONSE*
+```
+"event": {
+  "type": "FIXED_RESPONSE",
+  "params": {
+    "body": [
+      {
+        "createdDate": "2020-02-10",
+        "id": 123,
+        "state": "{$request.query.state}",
+        "reason": "string",
+        "changedDate": "2020-02-10"
+      }
+    ],
+    "statusCode": "200"
+  }
+}
+```
+
+### Priority of rules
+
+The 'priority' property in a rule dictates when rule should be run, relative to other rules. Higher priority rules are run before lower priority rules. Rules with the same priority are run in parallel. Priority must be a positive, non-zero integer.
+
+**Example:**
+
+Consider the following example, observe the priority values. So rule which compares the amount value will be executed first and then the other rule will be executed. So if the amount is equal to 50, then we will get FIXED_CALLBACK event in first place, and in other cases we get MOCK_CALLBACK.
+
+```
+[
+  {
+    "ruleId": 1,
+    "priority": 2,
+    "description": "If the transfer amount is equal to 50 USD, send a fixed callback",
+    "conditions": {
+      "all": [
+        {
+          "fact": "path",
+          "operator": "equal",
+          "value": "/transfers"
+        },
+        {
+          "fact": "method",
+          "operator": "equal",
+          "value": "post"
+        },
+        {
+          "fact": "body",
+          "operator": "equal",
+          "value": "50",
+          "path": "amount.amount"
+        }
+      ]
+    },
+    "event": {
+      "type": "FIXED_CALLBACK",
+      "params": {
+        ...Some fixed callback
+      }
+    }
+  },
+  {
+    "ruleId": 2,
+    "priority": 1,
+    "description": "Send a mock callback for all the remaining transfer requests",
+    "conditions": {
+      "all": [
+        {
+          "fact": "path",
+          "operator": "equal",
+          "value": "/transfers"
+        },
+        {
+          "fact": "method",
+          "operator": "equal",
+          "value": "post"
+        }
+      ]
+    },
+    "event": {
+      "type": "MOCK_CALLBACK",
+      "params": {
+      }
+    }
+  },
+```

package/documents/User-Guide-API-Provisioning.md

@@ -0,0 +1,121 @@
+# Mojaloop Testing Toolkit
+
+## _API Provisioning_
+
+**Table of Contents**
+
+1. [Overview](#1-overview)
+
+2. [Synchronous API](#2-synchronous-api)
+
+3. [Asynchronous API](#3-asynchronous-api)
+
+4. [Provisioning through UI](#4-api-provisioning-through-ui)
+
+5. [Prefix and Hostnames](#5-prefix-and-hostnames)
+
+
+## 1. Overview
+
+The Testing Toolkit is highly configurable and any API can be provisioned into TTK easily. 
+TTK supports two kinds of APIs
+
+* Synchronous API
+* Asynchronous API
+
+## 2. Synchronous API
+
+You just need to provide the **Swagger / OpenAPI** specification file of your synchronous API to the TTK.
+
+- Please copy the specification file in yaml format into the following folder
+  ```
+  spec_files/<your-api-folder-name>/api_spec.yaml
+  ```
+- Add a new entry to the property **API_DEFINITIONS** in _spec_files/system_config.json_
+  ```
+  {
+    "type": "<your-api-name>",
+    "version": "<major_version.minor_version",
+    "folderPath": "<your-api-folder-name>"
+  }
+  ```
+- Restart the testing toolkit service and that's it. You are all set.
+
+You should be able to send your API requests to TTK and the TTK will validate them against the specification. You can monitor them in the TTK UI.
+
+And also you can go ahead to create your own response rules to get customized responses from TTK through TTK UI.
+
+## 3. Asynchronous API
+
+You should follow the same procedure as Synchronous API and some additional steps are there to provision an Asynchronous API.
+
+- Please copy the specification file in yaml format into the following file
+  ```
+  spec_files/<your-api-folder-name>/api_spec.yaml
+  ```
+- Add a new entry to the property **API_DEFINITIONS** in _spec_files/system_config.json_. Please observe the additional _asynchronous_ flag here.
+  ```
+  {
+    "type": "<your-api-name>",
+    "version": "<major_version.minor_version",
+    "folderPath": "<your-api-folder-name>",
+    "asynchronous": true
+  }
+  ```
+- Additionally you should provide some information about callback mappings to associate the asynchronous callbacks to the respective requests. You can add that information into the following file. You can refer the sample files provided for FSPIOP api in the repository.
+  ```
+  spec_files/<your-api-folder-name>/callback_map.json
+  ```
+- Restart the testing toolkit service and that's it. You are all set.
+
+You should be able to send your API requests to TTK and the TTK will validate them against the specification. You can monitor them in the TTK UI.
+
+And also you can go ahead to create your own validation rules, callback rules and response rules to get customized / mock callbacks and responses from TTK through TTK UI.
+
+## 4. Provisioning through UI
+
+![Opening API Management](/assets/images/api-provisioning-menu-item.png)
+
+- You can go to _**API Management**_ navigation tab. Below is the default view of this API Management page.
+
+  ![API Management Default View](/assets/images/api-provisioning-list-apis-view.png)
+
+- Click on **Add new API** button, a popup window will be opened and you should drag / select your API specification yaml file there.
+
+  ![API Management File Input Window](/assets/images/api-provisioning-file-input-window.png)
+
+- After your file is been processed and validated by TTK, you can find the information about your API in the window. You can verify the details and change the name and other details populated there.
+
+  ![API Management Add New API Confirmation](/assets/images/api-provisioning-add-new-api-confirmation.png)
+
+## 5. Prefix and Hostnames
+
+We can also add a `prefix` to a provisioned API. For example if the API consists of a resource called `/pets`, we can configure a prefix for the pets api like `prefix: "/api"` in `system_config.json` file.
+Then the TTK accepts inbound requests on `/api/pets` instead of `/pets`.
+
+This is useful when two provisioned APIs have a common resource. Then we can clearly specify how TTK should work for the inbound requests on that common resource.
+
+**Note:** Prefix should always start with `/`
+
+In the same way we can also specify `hostnames` for an API. Then TTK selects the API based on the matching `hostname` of the inbound request. For example you can configure the hostname `127.0.0.1` for an API, then all that API will be selected only when the hostname of the inbound request in `127.0.0.1`. It doesn't match the inbound requests with the hostname `localhost`.
+
+Example configuration section of `system_config.json` file.
+```
+"API_DEFINITIONS": [
+  {
+    "type": "example-api-1",
+    "version": "1.0",
+    "folderPath": "example-api-1",
+    "hostnames": [],
+    "prefix": "/api1"
+  },
+  {
+    "type": "example-api-2",
+    "version": "1.0",
+    "folderPath": "example-api-2",
+    "hostnames": [
+      "example2.localhost.localdomain"
+    ]
+  }
+}
+```