diff --git a/README.md b/README.md index 5d5a6e4..3ab813e 100644 --- a/README.md +++ b/README.md @@ -77,6 +77,193 @@ The RETORCH framework provides a tool that generates an Execution Plan, along wi files for execution in a CI environment. The generation of scripts and pipelining code is based on the Access Modes annotated within the test cases and the Resource information specified in `/retorchfiles/[SUT_NAME]SystemResources.json`. +The RETORCH orchestration tool requires 4 inputs: +- The annotated E2E test cases with the [RETORCH access modes](#retorch-annotations). +- A file with the Resources in JSON format. +- A properties file with the Environment configuration. +- A custom `docker-compose.yml` file. + +Give this inputs, the tool generates as output the necessary scripting code and the `Jenkinsfile` to execute the E2E test +suite into a Continuous Integration system. + +### Prepare the E2E Test suite +To execute the RETORCH Orchestration tool and generate the script and pipelining code, requires to perform series of configurations +into the test suite. The first step is create several folders to store the configurations and place the docker-compose.yml +in the root of the repository. +The resulting directory tree should look like as: +``` +. +├── src +├── docker-compose.yml +├── retorchfiles/ +│ ├── configurations/ +│ └── customscriptscode/ + +``` +- The `retorchfiles/` directory would contain all the configuration files and scripting snippets that would be used to generate the +pipelining code as well as the scripts to set-up, deploy and tear-down the different Resources and TJob. Contains two subdirectories: + - `configurations/`: contains the Resource and CI configuration files + - `customscriptscode/`: stores the different script snippets for the tear-down, set-up and environment. +- The `docker-compose.yml` in the root of the directory. +- The different project directories-files. + +The following subsections explain how to create each configuration file and how to prepare the docker-compose.yml file. + +#### Create the Resource.json file +The Resource file must be placed in the `retorchfiles/configurations/` and named with the system or test suite name, followed +by `SystemResources.json`. This file contains a Map with a series of Resources, using as key their unique ResourceID. For each +Resource the tester needs specify the following attributes: +- `resourceID`: A unique identifier for the Resource. +- `replaceable`: A list of Resources that can replace the current one. +- `hierarchyParent`: A resourceID of the hierarchical parent of the Resource. +- `elasticityModel`: The elasticity model of the Resource, is composed by the following attributes: + - `elasticityID`: A unique identifier for the elasticity model. + - `elasticity`: Integer with the available Resources + - `elasticityCost`: Instantiation cost of each Resource +- `resourceType`: String with the type of the Resource(e.g. LOGICAL, PHYSICAL or COMPUTATIONAL) +- `minimalCapacities`: List with the Minimal Capacities required by the Resource, each Capacity is composed by: + - `name`: String between "memory","processor" and "storage" + - `quantity`: float with the amount fo Capacity Required: +- `dockerImage`: String with the concatenation of the placeholder name in the docker-compose, "[IMG:]" and the image name + +The following snippet shows an example of two Resources declared in the JSON file: + +```json +{ + "userservice": { + "hierarchyParent": ["mysql"], + "replaceable": [], + "elasticityModel": {"elasticityID": "elasmodeluserservice", "elasticity": 5, "elasticityCost": 30.0}, + "resourceType": "LOGICAL", "resourceID": "userservice", + "minimalCapacities": [ + {"name": "memory", "quantity": 0.2929}, + {"name": "processor", "quantity": 0.2}, + {"name": "storage", "quantity": 0.5}], + "dockerImage": "userservice[IMG:]wigo4it/identityserver4:latest" +}, + "frontend": { + "hierarchyParent": [], "replaceable": [], + "elasticityModel": {"elasticityID": "elasmodelfrontend", "elasticity": 1, "elasticityCost": 300.0}, + "resourceType": "LOGICAL", "resourceID": "frontend", + "minimalCapacities": [ + {"name": "memory", "quantity": 2}, + {"name": "processor", "quantity": 1}, + {"name": "storage", "quantity": 0.88}], + "dockerImage": "frontend[IMG:]nginx:latest" + } + +} +``` + +#### Create the retorchCI.properties file +The CI file must be placed in `retorchfiles/configurations/`, namely `retorchCI.properties` contain several parameters +related to the SUT and the Continuous Integration Infrastructure, has the following parameters: +- `agentCIName`: Specific Jenkins agent used to execute the test suite. +- `sut-wait-html`: State in the frontend (html displayed) when the SUT is ready for execute the test SUITE. +- `sut-location`: Location of the docker-compose file used to deploy the SUT. +- `docker-frontend-name`: ID of the container used as frontend . +- `docker-frontend-port`: PORT on which the frontend is available. +- `external-binded-port`: EXTERNAL PORT where the frontend is made available (if its available). +- `external-frontend-url`: EXTERNAL URI where the frontend is made available. +- `testsBasePath`: Path to the java project. + +The following snippet provides an example of how this file looks like: + +```properties + agentCIName=any + sut-wait-html=