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 ### Skeleton of a basic `uat.yaml`
  37
  38 ```yaml
  39 %YAML 1.1
  40 ---
  41 processes:
  42   - name: process1
  43     request:
  44       commonHeader: &commonHeader
  45         originatorId: sdnc
  46         requestId: "123456-1000"
  47         subRequestId: sub-123456-1000
  48       actionIdentifiers: &assign-ai
  49         blueprintName: configuration_over_restconf
  50         blueprintVersion: "1.0.0"
  51         actionName: config-assign
  52         mode: sync
  53       payload:
  54         # ...
  55     expectedResponse:
  56       commonHeader: *commonHeader
  57       actionIdentifiers: *assign-ai
  58       status:
  59         code: 200
  60         eventType: EVENT_COMPONENT_EXECUTED
  61         errorMessage: null
  62         message: success
  63       payload:
  64         # ...
  65       stepData:
  66         name: config-assign
  67         properties:
  68           resource-assignment-params:
  69             # ...
  70           status: success
  71   - name: process2
  72     # ...
  73
  74 external-services:
  75   - selector: odl
  76     expectations:
  77       - request:
  78           method: GET
  79           path:
  80         response:
  81           status: 200  # optional, 200 is the default value
  82           body: # optional, default is an empty content
  83             # ...
  84       - request:
  85           method: POST
  86           path:
  87           content-type: application/json
  88           body:
  89             # JSON request body
  90         response:
  91           status: 201
  92 ```
  93
  94 ### Composite URI paths
  95
  96 In case your YAML document contains many URI path definitions, you'd better keep the duplications
  97 as low as possible in order to ease the document maintenance, and avoid inconsistencies.
  98
  99 Since YAML doesn't provide a standard mechanism to concatenate strings,
 100 the UAT engine implements an ad-hoc mechanism based on multi-level lists.
 101 Please note that currently this mechanism is only applied to URI paths.
 102
 103 To exemplify how it works, let's take the case of eliminating duplications when defining multiple OpenDaylight URLs.
 104
 105 You might starting using the following definitions:
 106 ```yaml
 107    nodeId: &nodeId "new-netconf-device"
 108    # ...
 109    - request:
 110      path: &configUri [restconf/config, &nodeIdentifier [network-topology:network-topology/topology/topology-netconf/node, *nodeId]]
 111    # ...
 112    - request:
 113      path: [restconf/operational, *nodeIdentifier]
 114    # ...
 115    - request:
 116      path: [*configUri, &configletResourcePath yang-ext:mount/mynetconf:netconflist]
 117 ```
 118
 119 The UAT engine will expand the above multi-level lists, resulting on the following URI paths:
 120 ```yaml
 121    # ...
 122    - request:
 123      path: restconf/config/network-topology:network-topology/topology/topology-netconf/node/new-netconf-device
 124    # ...
 125    - request:
 126      path: restconf/operational/network-topology:network-topology/topology/topology-netconf/node/new-netconf-device
 127    # ...
 128    - request:
 129      path: restconf/config/network-topology:network-topology/topology/topology-netconf/node/new-netconf-device/yang-ext:mount/mynetconf:netconflist
 130 ```
 131
 132 ## License
 133
 134 Copyright (C) 2019 Nordix Foundation.
 135
 136 Licensed under the Apache License, Version 2.0 (the "License");
 137 you may not use this file except in compliance with the License.
 138 You may obtain a copy of the License at
 139
 140     http://www.apache.org/licenses/LICENSE-2.0
 141
 142 Unless required by applicable law or agreed to in writing, software
 143 distributed under the License is distributed on an "AS IS" BASIS,
 144 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 145 See the License for the specific language governing permissions and
 146 limitations under the License.