docs/cps-stubs.rst

   1 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
   2 .. http://creativecommons.org/licenses/by/4.0
   3 .. Copyright (C) 2023 Nordix Foundation
   4
   5 .. DO NOT CHANGE THIS LABEL FOR RELEASE NOTES - EVEN THOUGH IT GIVES A WARNING
   6
   7 .. _cpsStubs:
   8
   9
  10 CPS Stubs
  11 #########
  12
  13 .. toctree::
  14    :maxdepth: 1
  15
  16 NCMP Stubs
  17 ==========
  18
  19 The CPS NCMP stub module provides the capability to create dynamic and customizable stubs, offering control over the responses generated for each endpoint. This capability ensures that client interactions adhere to a specified NCMP interface, enabling comprehensive testing and validation of your applications.
  20
  21 The NCMP stub RestController is an extended implementation of the actual NCMP interface. It can be deployed as part of the application JAR or within a SpringBootTest JUnit environment, allowing you to define dynamic responses for each endpoint and  allowing testing against real stub interfaces.
  22
  23 Prerequisites
  24 =============
  25
  26 Ensure you meet the following prerequisites:
  27
  28 1. **Required Java Installation:**
  29
  30    Ensure that you have the required Java installed on your system.
  31
  32 2. **Access to Gerrit and Maven Installation (for building CPS project locally):**
  33
  34    - Ensure you have access to the ONAP Gerrit repository.
  35
  36    - If you plan to build the CPS project locally, make sure you have Maven installed.
  37
  38 Method 1: Running Stubs as an Application
  39 =========================================
  40
  41 Follow these steps to run the CPS-NCMP stub application:
  42
  43 1. **Download Application Jar:**
  44
  45    You can obtain the CPS-NCMP stub application jar in one of the following ways:
  46
  47    - **Option 1: Download from Nexus Repository:**
  48
  49      Download the application jar from the Nexus repository at `https://nexus.onap.org/content/repositories/releases/org/onap/cps/cps-ncmp-rest-stub-app/`_.
  50
  51    - **Option 2: Build Locally:**
  52
  53      To build the CPS project locally, navigate to the project's root directory. Once there, you can build the project using :code:`mvn clean install`, and the application CPS-NCMP stub application jar can be found in the following location:
  54
  55      ::
  56
  57        cps/cps-ncmp-rest-stub/cps-ncmp-rest-stub-app/target/
  58
  59 2. **Run the Application:**
  60
  61    After obtaining the application jar, use the following command to run it:
  62
  63    .. code-block:: bash
  64
  65       java -jar ./cps-ncmp-rest-stub-app-<VERSION>.jar
  66
  67    Replace ``<VERSION>`` with the actual version number of the application jar.
  68
  69 This will start the CPS-NCMP stub application, and you can interact with it as needed.
  70
  71 .. _`https://nexus.onap.org/content/repositories/releases/org/onap/cps/cps-ncmp-rest-stub-app/`: https://nexus.onap.org/content/repositories/releases/org/onap/cps/cps-ncmp-rest-stub-app/
  72
  73 Method 2: Using Stubs in Unit Tests
  74 ===================================
  75 1. **Add Dependency to pom.xml:**
  76
  77    To include the required module in your project, add the following dependency to your `pom.xml` file:
  78
  79    .. code-block:: xml
  80
  81       <dependency>
  82         <groupId>org.onap.cps</groupId>
  83         <artifactId>cps-ncmp-rest-stub-service</artifactId>
  84         <version>VERSION</version>
  85      </dependency>
  86
  87    Replace ``VERSION`` with the actual version number.
  88
  89 2. **Using Custom Response Objects:**
  90
  91    If you prefer to use custom response objects instead of the built-in ones, follow these steps:
  92
  93    Modify the `application.yaml` file located in your project's test resources directory (`src/test/resources`).
  94
  95    Add the following property to the `application.yaml` file, specifying the directory that contains your custom response objects:
  96
  97    .. code-block:: yaml
  98
  99       stub:
 100           path: "/my_custom_stubs/"
 101
 102    **Note:** Custom response objects can be placed in the `src/test/resources` directory of your project under the directory defined in above property. Refer to the `examples <https://github.com/onap/cps/tree/master/cps-ncmp-rest-stub/cps-ncmp-rest-stub-service/src/main/resources/stubs>`_ included in the CPS source repository for reference.
 103
 104 3. **Simple Test Code:**
 105
 106    You may refer to the sample test code 'SampleCpsNcmpClientSpec.groovy' in the local CPS project under the following directory:
 107
 108    ::
 109
 110      /cps/cps-ncmp-rest-stub/cps-ncmp-rest-stub-service/src/test/groovy/org/onap/cps/ncmp/rest/stub/
 111
 112    Alternatively, you can refer to the `example <https://github.com/onap/cps/tree/master/cps-ncmp-rest-stub/cps-ncmp-rest-stub-service/src/test/groovy/org/onap/cps/ncmp/rest/stub>`_ included in the CPS source repository.
 113
 114 **Custom Responses for Supported Endpoints**
 115
 116   Only the following endpoints are supported for the first draft. To use your custom response objects for these endpoints, create the corresponding JSON files:
 117
 118   - For RequestMethod.GET /v1/ch/{cm-handle}/data/ds/{datastore-name}, create "passthrough-operational-example.json".
 119
 120   - For RequestMethod.POST /v1/ch/searches, create "cmHandlesSearch.json".