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         required Response response = 2;
  65     }
  66
  67     message ExternalService {
  68         required string selector = 1;
  69         repeated Expectation expectations = 2;      // min cardinality = 1
  70     }
  71
  72     repeated Process processes = 1;                 // min cardinality = 1
  73     repeated ExternalService externalServices = 2;  // min cardinality = 0
  74 }
  75
  76 ```
  77
  78 The optional `responseNormalizerSpec` specifies transformations that may be needed to apply to the response
  79 returned by BPP to get a full JSON representation. For example, it's possible to convert an string field "outer.inner"
  80 into JSON using the following specification:
  81
  82 ```yaml
  83     responseNormalizerSpec:
  84       outer:
  85         inner: ?from-json(.outer.inner)
  86
  87 ```
  88
  89 The "?" must prefix every expression that is NOT a literal string. The `from-json()` function and
  90 many others are documented [here](https://github.com/schibsted/jslt/blob/0.1.8/functions.md).
  91
  92 ### Skeleton of a basic `uat.yaml`
  93
  94 ```yaml
  95 %YAML 1.1
  96 ---
  97 processes:
  98   - name: process1
  99     request:
 100       commonHeader: &commonHeader
 101         originatorId: sdnc
 102         requestId: "123456-1000"
 103         subRequestId: sub-123456-1000
 104       actionIdentifiers: &assign-ai
 105         blueprintName: configuration_over_restconf
 106         blueprintVersion: "1.0.0"
 107         actionName: config-assign
 108         mode: sync
 109       payload:
 110         # ...
 111     expectedResponse:
 112       commonHeader: *commonHeader
 113       actionIdentifiers: *assign-ai
 114       status:
 115         code: 200
 116         eventType: EVENT_COMPONENT_EXECUTED
 117         errorMessage: null
 118         message: success
 119       payload:
 120         # ...
 121       stepData:
 122         name: config-assign
 123         properties:
 124           resource-assignment-params:
 125             # ...
 126           status: success
 127   - name: process2
 128     # ...
 129
 130 external-services:
 131   - selector: odl
 132     expectations:
 133       - request:
 134           method: GET
 135           path:
 136         response:
 137           status: 200  # optional, 200 is the default value
 138           body: # optional, default is an empty content
 139             # ...
 140       - request:
 141           method: POST
 142           path:
 143           content-type: application/json
 144           body:
 145             # JSON request body
 146         response:
 147           status: 201
 148 ```
 149
 150 ### Composite URI paths
 151
 152 In case your YAML document contains many URI path definitions, it's recommended to keep the duplications
 153 as low as possible in order to ease the document maintenance, and avoid inconsistencies.
 154
 155 Since YAML doesn't provide a standard mechanism to concatenate strings,
 156 the UAT engine implements an ad-hoc mechanism based on multi-level lists.
 157 Please note that currently this mechanism is only applied to URI paths.
 158
 159 To exemplify how it works, let's take the case of eliminating duplications when defining multiple OpenDaylight URLs.
 160
 161 You might start using the following definitions:
 162 ```yaml
 163    nodeId: &nodeId "new-netconf-device"
 164    # ...
 165    - request:
 166      path: &configUri [restconf/config, &nodeIdentifier [network-topology:network-topology/topology/topology-netconf/node, *nodeId]]
 167    # ...
 168    - request:
 169      path: [restconf/operational, *nodeIdentifier]
 170    # ...
 171    - request:
 172      path: [*configUri, &configletResourcePath yang-ext:mount/mynetconf:netconflist]
 173 ```
 174
 175 The UAT engine will expand the above multi-level lists, resulting on the following URI paths:
 176 ```yaml
 177    # ...
 178    - request:
 179      path: restconf/config/network-topology:network-topology/topology/topology-netconf/node/new-netconf-device
 180    # ...
 181    - request:
 182      path: restconf/operational/network-topology:network-topology/topology/topology-netconf/node/new-netconf-device
 183    # ...
 184    - request:
 185      path: restconf/config/network-topology:network-topology/topology/topology-netconf/node/new-netconf-device/yang-ext:mount/mynetconf:netconflist
 186 ```
 187
 188 ## License
 189
 190 Copyright (C) 2019 Nordix Foundation.
 191
 192 Licensed under the Apache License, Version 2.0 (the "License");
 193 you may not use this file except in compliance with the License.
 194 You may obtain a copy of the License at https://www.apache.org/licenses/LICENSE-2.0
 195
 196 Unless required by applicable law or agreed to in writing, software
 197 distributed under the License is distributed on an "AS IS" BASIS,
 198 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 199 See the License for the specific language governing permissions and
 200 limitations under the License.