components/model-catalog/blueprint-model/uat-blueprints/README.md

   1 # Acceptance Testing Blueprints
   2
   3 ## What is BP User Acceptance Tests (UATs)?
   4
   5 UATs aims to fully test the BlueprintsProcessor (BPP) using a blueprint.
   6 The BPP runs in an almost production-like configuration with some minor exceptions:
   7
   8 - It uses an embedded, in-memory, and initially empty H2 database, running in MySQL/MariaDB compatibility mode;
   9 - All external services are mocked.
  10
  11 ## How it works?
  12
  13 The UATs are declarative, data-driven tests implemented in YAML 1.1 documents.
  14 This YAML files express:
  15
  16 - Sequence of requests to be sent to the BPP for every process;
  17 - The expected BPP responses;
  18 - For every used external service:
  19   - The `selector` used internally to instantiate the rest client;
  20   - A variable set of expected requests and corresponding responses.
  21
  22 The UAT engine will perform the following validations:
  23
  24 - The BPP responses;
  25 - The payloads in the external services requests and it's content type.
  26
  27 ## Adding your BP to the suite of UATs
  28
  29 To add a new BP to the UAT suite, all you need to do is:
  30 1. Add your blueprint folder under
  31 CDS project's `components/model-catalog/blueprint-model/uat-blueprints` directory;
  32 2. Create a `Tests/uat.yaml` document under your BP folder.
  33
  34 ## `uat.yaml` reference
  35
  36 The structure of an UAT YAML file could be documented using the Protobuf language as follows:
  37
  38 ```proto
  39 message Uat {
  40     message Path {}
  41     message Json {}
  42
  43     message Process {
  44         required string name = 1;
  45         required Json request = 2;
  46         required Json expectedResponse = 3;
  47         optional Json responseNormalizerSpec = 4;
  48     }
  49
  50     message Request {
  51         required string method = 1;
  52         required Path path = 2;
  53         optional string contentType = 3 [default = None];
  54         optional Json body = 4;
  55     }
  56
  57     message Response {
  58         optional int32 status = 1 [default = 200];
  59         optional Json body = 2;
  60     }
  61
  62     message Expectation {
  63         required Request request = 1;
  64         optional Response response = 2;
  65         repeated Response responses = 3;
  66     }
  67
  68     message ExternalService {
  69         required string selector = 1;
  70         repeated Expectation expectations = 2;      // min cardinality = 1
  71     }
  72
  73     repeated Process processes = 1;                 // min cardinality = 1
  74     repeated ExternalService externalServices = 2;  // min cardinality = 0
  75 }
  76
  77 ```
  78
  79 The optional `responseNormalizerSpec` specifies transformations that may be needed to apply to the response
  80 returned by BPP to get a full JSON representation. For example, it's possible to convert an string field "outer.inner"
  81 into JSON using the following specification:
  82
  83 ```yaml
  84     responseNormalizerSpec:
  85       outer:
  86         inner: ?from-json(.outer.inner)
  87
  88 ```
  89
  90 The "?" must prefix every expression that is NOT a literal string. The `from-json()` function and
  91 many others are documented [here](https://github.com/schibsted/jslt/blob/0.1.8/functions.md).
  92
  93 ### Skeleton of a basic `uat.yaml`
  94
  95 ```yaml
  96 %YAML 1.1
  97 ---
  98 processes:
  99   - name: process1
 100     request:
 101       commonHeader: &commonHeader
 102         originatorId: sdnc
 103         requestId: "123456-1000"
 104         subRequestId: sub-123456-1000
 105       actionIdentifiers: &assign-ai
 106         blueprintName: configuration_over_restconf
 107         blueprintVersion: "1.0.0"
 108         actionName: config-assign
 109         mode: sync
 110       payload:
 111         # ...
 112     expectedResponse:
 113       commonHeader: *commonHeader
 114       actionIdentifiers: *assign-ai
 115       status:
 116         code: 200
 117         eventType: EVENT_COMPONENT_EXECUTED
 118         errorMessage: null
 119         message: success
 120       payload:
 121         # ...
 122       stepData:
 123         name: config-assign
 124         properties:
 125           resource-assignment-params:
 126             # ...
 127           status: success
 128   - name: process2
 129     # ...
 130
 131 external-services:
 132   - selector: odl
 133     expectations:
 134       - request:
 135           method: GET
 136           path:
 137         response:
 138           status: 200  # optional, 200 is the default value
 139           body: # optional, default is an empty content
 140             # ...
 141       - request:
 142           method: POST
 143           path:
 144           content-type: application/json
 145           body:
 146             # JSON request body
 147         response:
 148           status: 201
 149 ```
 150
 151 ### Composite URI paths
 152
 153 In case your YAML document contains many URI path definitions, it's recommended to keep the duplications
 154 as low as possible in order to ease the document maintenance, and avoid inconsistencies.
 155
 156 Since YAML doesn't provide a standard mechanism to concatenate strings,
 157 the UAT engine implements an ad-hoc mechanism based on multi-level lists.
 158 Please note that currently this mechanism is only applied to URI paths.
 159
 160 To exemplify how it works, let's take the case of eliminating duplications when defining multiple OpenDaylight URLs.
 161
 162 You might start using the following definitions:
 163 ```yaml
 164    nodeId: &nodeId "new-netconf-device"
 165    # ...
 166    - request:
 167      path: &configUri [restconf/config, &nodeIdentifier [network-topology:network-topology/topology/topology-netconf/node, *nodeId]]
 168    # ...
 169    - request:
 170      path: [restconf/operational, *nodeIdentifier]
 171    # ...
 172    - request:
 173      path: [*configUri, &configletResourcePath yang-ext:mount/mynetconf:netconflist]
 174 ```
 175
 176 The UAT engine will expand the above multi-level lists, resulting on the following URI paths:
 177 ```yaml
 178    # ...
 179    - request:
 180      path: restconf/config/network-topology:network-topology/topology/topology-netconf/node/new-netconf-device
 181    # ...
 182    - request:
 183      path: restconf/operational/network-topology:network-topology/topology/topology-netconf/node/new-netconf-device
 184    # ...
 185    - request:
 186      path: restconf/config/network-topology:network-topology/topology/topology-netconf/node/new-netconf-device/yang-ext:mount/mynetconf:netconflist
 187 ```
 188
 189 ## License
 190
 191 Copyright (C) 2019 Nordix Foundation.
 192
 193 Licensed under the Apache License, Version 2.0 (the "License");
 194 you may not use this file except in compliance with the License.
 195 You may obtain a copy of the License at https://www.apache.org/licenses/LICENSE-2.0
 196
 197 Unless required by applicable law or agreed to in writing, software
 198 distributed under the License is distributed on an "AS IS" BASIS,
 199 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 200 See the License for the specific language governing permissions and
 201 limitations under the License.