diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/cps-path.rst | 4 | ||||
| -rw-r--r-- | docs/cps-stubs.rst | 120 | ||||
| -rw-r--r-- | docs/deployment.rst | 4 | ||||
| -rwxr-xr-x | docs/design.rst | 23 | ||||
| -rwxr-xr-x | docs/index.rst | 1 | ||||
| -rwxr-xr-x | docs/release-notes.rst | 8 | ||||
| -rw-r--r-- | docs/spelling_wordlist.txt | 67 | ||||
| -rw-r--r-- | docs/tox.ini | 10 |
8 files changed, 223 insertions, 14 deletions
diff --git a/docs/cps-path.rst b/docs/cps-path.rst index 6611789544..eb203d8918 100644 --- a/docs/cps-path.rst +++ b/docs/cps-path.rst @@ -247,7 +247,7 @@ leaf-conditions - Using comparative operators with string values will lead to an error at runtime. This error can't be validated earlier as the datatype is unknown until the execution phase. - The key should be supplied with correct data type for it to be queried from DB. In the last example above the attribute code is of type Integer so the cps query will not work if the value is passed as string. - eg: ``//categories[@code="1"]`` or ``//categories[@code='1']`` will not work because the key attribute code is treated a string. + e.g.: ``//categories[@code="1"]`` or ``//categories[@code='1']`` will not work because the key attribute code is treated a string. **Notes** - For performance reasons it does not make sense to query using key leaf as attribute. If the key value is known it is better to execute a get request with the complete xpath. @@ -260,7 +260,7 @@ The text()-condition can be added to any CPS path query. **Syntax**: ``<cps-path> ( '/' <leaf-name> '[text()=' <string-value> ']' )?`` - ``cps-path``: Any CPS path query. - ``leaf-name``: The name of the leaf or leaf-list which value needs to be compared. - - ``string-value``: The required value of the leaf or leaf-list element as a string wrapped in quotation marks (U+0022) or apostrophes (U+0027). This wil still match integer values. + - ``string-value``: The required value of the leaf or leaf-list element as a string wrapped in quotation marks (U+0022) or apostrophes (U+0027). This will still match integer values. **Examples** - ``//book/label[text()="classic"]`` diff --git a/docs/cps-stubs.rst b/docs/cps-stubs.rst new file mode 100644 index 0000000000..00577eb0d9 --- /dev/null +++ b/docs/cps-stubs.rst @@ -0,0 +1,120 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 +.. Copyright (C) 2023 Nordix Foundation + +.. DO NOT CHANGE THIS LABEL FOR RELEASE NOTES - EVEN THOUGH IT GIVES A WARNING + +.. _cpsStubs: + + +CPS Stubs +######### + +.. toctree:: + :maxdepth: 1 + +NCMP Stubs +========== + +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. + +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. + +Prerequisites +============= + +Ensure you meet the following prerequisites: + +1. **Required Java Installation:** + + Ensure that you have the required Java installed on your system. + +2. **Access to Gerrit and Maven Installation (for building CPS project locally):** + + - Ensure you have access to the ONAP Gerrit repository. + + - If you plan to build the CPS project locally, make sure you have Maven installed. + +Method 1: Running Stubs as an Application +========================================= + +Follow these steps to run the CPS-NCMP stub application: + +1. **Download Application Jar:** + + You can obtain the CPS-NCMP stub application jar in one of the following ways: + + - **Option 1: Download from Nexus Repository:** + + Download the application jar from the Nexus repository at `https://nexus.onap.org/content/repositories/releases/org/onap/cps/cps-ncmp-rest-stub-app/`_. + + - **Option 2: Build Locally:** + + 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: + + :: + + cps/cps-ncmp-rest-stub/cps-ncmp-rest-stub-app/target/ + +2. **Run the Application:** + + After obtaining the application jar, use the following command to run it: + + .. code-block:: bash + + java -jar ./cps-ncmp-rest-stub-app-<VERSION>.jar + + Replace ``<VERSION>`` with the actual version number of the application jar. + +This will start the CPS-NCMP stub application, and you can interact with it as needed. + +.. _`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/ + +Method 2: Using Stubs in Unit Tests +=================================== +1. **Add Dependency to pom.xml:** + + To include the required module in your project, add the following dependency to your `pom.xml` file: + + .. code-block:: xml + + <dependency> + <groupId>org.onap.cps</groupId> + <artifactId>cps-ncmp-rest-stub-service</artifactId> + <version>VERSION</version> + </dependency> + + Replace ``VERSION`` with the actual version number. + +2. **Using Custom Response Objects:** + + If you prefer to use custom response objects instead of the built-in ones, follow these steps: + + Modify the `application.yaml` file located in your project's test resources directory (`src/test/resources`). + + Add the following property to the `application.yaml` file, specifying the directory that contains your custom response objects: + + .. code-block:: yaml + + stub: + path: "/my_custom_stubs/" + + **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. + +3. **Simple Test Code:** + + You may refer to the sample test code 'SampleCpsNcmpClientSpec.groovy' in the local CPS project under the following directory: + + :: + + /cps/cps-ncmp-rest-stub/cps-ncmp-rest-stub-service/src/test/groovy/org/onap/cps/ncmp/rest/stub/ + + 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. + +**Custom Responses for Supported Endpoints** + + Only the following endpoints are supported for the first draft. To use your custom response objects for these endpoints, create the corresponding JSON files: + + - For RequestMethod.GET /v1/ch/{cm-handle}/data/ds/{datastore-name}, create "passthrough-operational-example.json". + + - For RequestMethod.POST /v1/ch/searches, create "cmHandlesSearch.json". diff --git a/docs/deployment.rst b/docs/deployment.rst index 0642e6a8e1..0fee55969a 100644 --- a/docs/deployment.rst +++ b/docs/deployment.rst @@ -197,8 +197,8 @@ Any spring supported property can be configured by providing in ``config.additio | logging.level | Logging level set in cps-core | info | | | | | +---------------------------------------+---------------------------------------------------------------------------------------------------------+-------------------------------+ -| config.useStrimziKafka | If targeting a custom kafka cluster, ie useStrimziKafka: false, the config.eventPublisher.spring.kafka | true | -| | values below must be set. | | +| config.useStrimziKafka | If targeting a custom kafka cluster, i.e. useStrimziKafka: false, the | true | +| | config.eventPublisher.spring.kafka values below must be set. | | +---------------------------------------+---------------------------------------------------------------------------------------------------------+-------------------------------+ | config.eventPublisher. | Kafka hostname and port | ``<kafka-bootstrap>:9092`` | | spring.kafka.bootstrap-servers | | | diff --git a/docs/design.rst b/docs/design.rst index 5ad86a3aed..80eb5f1523 100755 --- a/docs/design.rst +++ b/docs/design.rst @@ -1,6 +1,6 @@ .. This work is licensed under a Creative Commons Attribution 4.0 International License. .. http://creativecommons.org/licenses/by/4.0 -.. Copyright (C) 2021-2022 Nordix Foundation +.. Copyright (C) 2021-2023 Nordix Foundation .. DO NOT CHANGE THIS LABEL FOR RELEASE NOTES - EVEN THOUGH IT GIVES A WARNING .. _design: @@ -93,3 +93,24 @@ NCMP uses common responses codes in REST responses and events. Also the DMI plug :maxdepth: 1 cps-ncmp-message-status-codes.rst + +Contract Testing (stubs) +======================== + +The CPS team is committed to supporting consumers of our APIs through contract testing. +Obviously we test our own contracts on a continuous basis as part of the build and delivery process. +CPS uses a contract-first approach. That means we write our OpenAPi contracts first and then generate the interface code from that. +This means our interface implementation simply cannot deviate from the OpenApi contracts we deliver. + +Another advantage is that we can also generate 'stubs'. Stubs are a basic implementation of the same interface for testing purposes. +These stubs can be used by clients for unit testing but also for more higher level integration-like testing where the real service is replaced by a stub. +This can be useful for faster feedback loops where deployment of a full stack is difficult and not strictly needed for the purpose of the tests. + +Stubs for contract testing typically always return the same response which is sufficient for the strict definition of a contract test. +However it is often useful to allow more variation in the responses so different clients or the same client can test different scenarios without having to mock the service. +CPS has implemented what we call 'extended stubs' that allow clients to provide alternate responses.implementation + +The available stubs and how to use them are described in :doc:'cps-stubs'. + + + diff --git a/docs/index.rst b/docs/index.rst index c1427ad381..573bd54122 100755 --- a/docs/index.rst +++ b/docs/index.rst @@ -25,6 +25,7 @@ CPS cps-events.rst deployment.rst release-notes.rst + cps-stubs.rst DMI-Plugin ========== diff --git a/docs/release-notes.rst b/docs/release-notes.rst index d891162c32..e6b81fcbaf 100755 --- a/docs/release-notes.rst +++ b/docs/release-notes.rst @@ -515,7 +515,7 @@ Bug Fixes - `CPS-1289 <https://jira.onap.org/browse/CPS-1289>`_ Getting wrong error code for create node api - `CPS-1326 <https://jira.onap.org/browse/CPS-1326>`_ Creation of DataNodeBuilder with module name prefix is very slow - `CPS-1344 <https://jira.onap.org/browse/CPS-1344>`_ Top level container (prefix) is not always the first module - - `CPS-1350 <https://jira.onap.org/browse/CPS-1350>`_ Add Basic Auth to CPS/NCMP OpenAPI Definitions. + - `CPS-1350 <https://jira.onap.org/browse/CPS-1350>`_ Add Basic Authentication to CPS/NCMP OpenAPI Definitions. - `CPS-1352 <https://jira.onap.org/browse/CPS-1352>`_ Handle YangChoiceNode in right format. - `CPS-1409 <https://jira.onap.org/browse/CPS-1409>`_ Fix Delete uses case with '/' in path. - `CPS-1433 <https://jira.onap.org/browse/CPS-1433>`_ Fix to allow posting data with '/' key fields. @@ -701,7 +701,7 @@ Bug Fixes - `CPS-957 <https://jira.onap.org/browse/CPS-957>`_ NCMP: fix getResourceDataForPassthroughOperational endpoint - `CPS-1020 <https://jira.onap.org/browse/CPS-1020>`_ DuplicatedYangResourceException error at parallel cmHandle registration - `CPS-1056 <https://jira.onap.org/browse/CPS-1056>`_ Wrong error response format in case of Dmi plugin error - - `CPS-1067 <https://jira.onap.org/browse/CPS-1067>`_ NCMP returns 500 error on searches endpoint when No DMi Handles registered + - `CPS-1067 <https://jira.onap.org/browse/CPS-1067>`_ NCMP returns 500 error on searches endpoint when No DMI Handles registered - `CPS-1085 <https://jira.onap.org/browse/CPS-1085>`_ Performance degradation on ncmp/v1/ch/searches endpoint - `CPS-1088 <https://jira.onap.org/browse/CPS-1088>`_ Kafka consumer can not be turned off - `CPS-1097 <https://jira.onap.org/browse/CPS-1097>`_ Unable to change state from LOCKED to ADVISED @@ -813,7 +813,7 @@ Bug Fixes - `CPS-886 <https://jira.onap.org/browse/CPS-886>`_ Fragment handling decreasing performance for large number of cmHandles - `CPS-887 <https://jira.onap.org/browse/CPS-887>`_ Increase performance of cmHandle registration for large number of schema sets in DB - `CPS-892 <https://jira.onap.org/browse/CPS-892>`_ Fixed the response code during CM-Handle Registration from 201 CREATED to 204 NO_CONTENT - - `CPS-893 <https://jira.onap.org/browse/CPS-893>`_ NCMP Java API depends on NCM-Rest-API (cyclic) through json properties on Java API + - `CPS-893 <https://jira.onap.org/browse/CPS-893>`_ NCMP Java API depends on NCMP-Rest-API (cyclic) through json properties on Java API Known Limitations, Issues and Workarounds ----------------------------------------- @@ -1268,7 +1268,7 @@ Security Notes *Known Security Issues* - * Weak Crytography using md5 + * Weak Cryptography using md5 * Risk seen in Zip file expansion *Known Vulnerabilities in Used Modules* diff --git a/docs/spelling_wordlist.txt b/docs/spelling_wordlist.txt new file mode 100644 index 0000000000..3bfa9a0a31 --- /dev/null +++ b/docs/spelling_wordlist.txt @@ -0,0 +1,67 @@ +api +async +authorization +boolean +behavior +camelCasing +cmHandle +cmHandles +config +color +cps +cpsPath +cpsPaths +csit +customizations +dataschema +dataspace +dataspaces +datasource +datastore +datastores +deliverables +dmi +dmiPlugin +dmiPlugins +rnv +hazelcast +hostname +jira +json +kafka +kibana +kubernetes +kohn +lifecycle +liquibase +logback +modeled +modeling +normalized +ncmp +onap +openapi +optimized +passthrough +performant +postgres +queryable +repo +runtime +schemas +sql +ssl +standardized +synchronize +synchronization +undeploying +utilizes +xml +xNF +xNFs +xpath +xpaths +xPath +XPath +XPaths +yaml
\ No newline at end of file diff --git a/docs/tox.ini b/docs/tox.ini index 8684276f97..7020752c8c 100644 --- a/docs/tox.ini +++ b/docs/tox.ini @@ -21,23 +21,23 @@ minversion = 1.6 envlist = docs,docs-linkcheck,docs-spellcheck skipsdist = true [testenv:docs] -basepython = python3.8 +basepython = python3.10 deps = -r{toxinidir}/requirements-docs.txt -chttps://raw.githubusercontent.com/openstack/requirements/stable/yoga/upper-constraints.txt -chttps://git.onap.org/doc/plain/etc/upper-constraints.onap.txt?h=master commands = - sphinx-build -W -q -b html -n -d {envtmpdir}/doctrees {toxinidir} {toxinidir}/_build/html + sphinx-build -q -b html -n -d {envtmpdir}/doctrees {toxinidir} {toxinidir}/_build/html [testenv:docs-linkcheck] -basepython = python3.8 +basepython = python3.10 deps = -r{toxinidir}/requirements-docs.txt -chttps://raw.githubusercontent.com/openstack/requirements/stable/yoga/upper-constraints.txt -chttps://git.onap.org/doc/plain/etc/upper-constraints.onap.txt?h=master commands = - sphinx-build -W -q -b linkcheck -d {envtmpdir}/doctrees {toxinidir} {toxinidir}/_build/linkcheck + sphinx-build -q -b linkcheck -d {envtmpdir}/doctrees {toxinidir} {toxinidir}/_build/linkcheck [testenv:docs-spellcheck] -basepython = python3.8 +basepython = python3.10 deps = -r{toxinidir}/requirements-docs.txt -chttps://raw.githubusercontent.com/openstack/requirements/stable/yoga/upper-constraints.txt |