Add document for apex-pdp smoke test
[policy/parent.git] / docs / development / devtools / devtools.rst
1 .. This work is licensed under a
2 .. Creative Commons Attribution 4.0 International License.
3 .. http://creativecommons.org/licenses/by/4.0
4
5 .. _policy-development-tools-label:
6
7 Policy Platform Development Tools
8 #################################
9
10 .. contents::
11     :depth: 3
12
13
14 This article explains how to build the ONAP Policy Framework for development purposes and how to run stability/performance tests for a variety of components. To start, the developer should consult the latest ONAP Wiki to familiarize themselves with developer best practices and how-tos to setup their environment, see `https://wiki.onap.org/display/DW/Developer+Best+Practices`.
15
16
17 This article assumes that:
18
19 * You are using a *\*nix* operating system such as linux or macOS.
20 * You are using a directory called *git* off your home directory *(~/git)* for your git repositories
21 * Your local maven repository is in the location *~/.m2/repository*
22 * You have copied the settings.xml from oparent to *~/.m2/* directory
23 * You have added settings to access the ONAP Nexus to your M2 configuration, see `Maven Settings Example <https://wiki.onap.org/display/DW/Setting+Up+Your+Development+Environment>`_ (bottom of the linked page)
24
25 The procedure documented in this article has been verified to work on a MacBook laptop running macOS Mojave Version 10.14.6 and an Unbuntu 18.06 VM.
26
27 Cloning All The Policy Repositories
28 ***********************************
29
30 Run a script such as the script below to clone the required modules from the `ONAP git repository <https://gerrit.onap.org/r/#/admin/projects/?filter=policy>`_. This script clones all the ONAP Policy Framework repositories.
31
32 ONAP Policy Framework has dependencies to the ONAP Parent *oparent* module, the ONAP ECOMP SDK *ecompsdkos* module, and the A&AI Schema module.
33
34
35 .. code-block:: bash
36    :caption: Typical ONAP Policy Framework Clone Script
37    :linenos:
38
39     #!/usr/bin/env bash
40
41     ## script name for output
42     MOD_SCRIPT_NAME=`basename $0`
43
44     ## the ONAP clone directory, defaults to "onap"
45     clone_dir="onap"
46
47     ## the ONAP repos to clone
48     onap_repos="\
49     policy/parent \
50     policy/common \
51     policy/models \
52     policy/docker \
53     policy/api \
54     policy/pap \
55     policy/apex-pdp \
56     policy/drools-pdp \
57     policy/drools-applications \
58     policy/xacml-pdp \
59     policy/distribution \
60     policy/gui \
61     policy/clamp "
62
63     ##
64     ## Help screen and exit condition (i.e. too few arguments)
65     ##
66     Help()
67     {
68         echo ""
69         echo "$MOD_SCRIPT_NAME - clones all required ONAP git repositories"
70         echo ""
71         echo "       Usage:  $MOD_SCRIPT_NAME [-options]"
72         echo ""
73         echo "       Options"
74         echo "         -d          - the ONAP clone directory, defaults to '.'"
75         echo "         -h          - this help screen"
76         echo ""
77         exit 255;
78     }
79
80     ##
81     ## read command line
82     ##
83     while [ $# -gt 0 ]
84     do
85         case $1 in
86             #-d ONAP clone directory
87             -d)
88                 shift
89                 if [ -z "$1" ]; then
90                     echo "$MOD_SCRIPT_NAME: no clone directory"
91                     exit 1
92                 fi
93                 clone_dir=$1
94                 shift
95             ;;
96
97             #-h prints help and exists
98             -h)
99                 Help;exit 0;;
100
101             *)    echo "$MOD_SCRIPT_NAME: undefined CLI option - $1"; exit 255;;
102         esac
103     done
104
105     if [ -f "$clone_dir" ]; then
106         echo "$MOD_SCRIPT_NAME: requested clone directory '$clone_dir' exists as file"
107         exit 2
108     fi
109     if [ -d "$clone_dir" ]; then
110         echo "$MOD_SCRIPT_NAME: requested clone directory '$clone_dir' exists as directory"
111         exit 2
112     fi
113
114     mkdir $clone_dir
115     if [ $? != 0 ]
116     then
117         echo cannot clone ONAP repositories, could not create directory '"'$clone_dir'"'
118         exit 3
119     fi
120
121     for repo in $onap_repos
122     do
123         repoDir=`dirname "$repo"`
124         repoName=`basename "$repo"`
125
126         if [ ! -z $dirName ]
127         then
128             mkdir "$clone_dir/$repoDir"
129             if [ $? != 0 ]
130             then
131                 echo cannot clone ONAP repositories, could not create directory '"'$clone_dir/repoDir'"'
132                 exit 4
133             fi
134         fi
135
136         git clone https://gerrit.onap.org/r/${repo} $clone_dir/$repo
137     done
138
139     echo ONAP has been cloned into '"'$clone_dir'"'
140
141
142 Execution of the script above results in the following directory hierarchy in your *~/git* directory:
143
144     *  ~/git/onap
145     *  ~/git/onap/policy
146     *  ~/git/onap/policy/parent
147     *  ~/git/onap/policy/common
148     *  ~/git/onap/policy/models
149     *  ~/git/onap/policy/api
150     *  ~/git/onap/policy/pap
151     *  ~/git/onap/policy/gui
152     *  ~/git/onap/policy/docker
153     *  ~/git/onap/policy/drools-applications
154     *  ~/git/onap/policy/drools-pdp
155     *  ~/git/onap/policy/clamp
156     *  ~/git/onap/policy/apex-pdp
157     *  ~/git/onap/policy/xacml-pdp
158     *  ~/git/onap/policy/distribution
159
160
161 Building ONAP Policy Framework Components
162 *****************************************
163
164 **Step 1:** Optionally, for a completely clean build, remove the ONAP built modules from your local repository.
165
166     .. code-block:: bash
167
168         rm -fr ~/.m2/repository/org/onap
169
170
171 **Step 2:**  A pom such as the one below can be used to build the ONAP Policy Framework modules. Create the *pom.xml* file in the directory *~/git/onap/policy*.
172
173 .. code-block:: xml
174    :caption: Typical pom.xml to build the ONAP Policy Framework
175    :linenos:
176
177     <project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
178         <modelVersion>4.0.0</modelVersion>
179         <groupId>org.onap</groupId>
180         <artifactId>onap-policy</artifactId>
181         <version>1.0.0-SNAPSHOT</version>
182         <packaging>pom</packaging>
183         <name>${project.artifactId}</name>
184         <inceptionYear>2017</inceptionYear>
185         <organization>
186             <name>ONAP</name>
187         </organization>
188
189         <modules>
190             <module>parent</module>
191             <module>common</module>
192             <module>models</module>
193             <module>api</module>
194             <module>pap</module>
195             <module>apex-pdp</module>
196             <module>xacml-pdp</module>
197             <module>drools-pdp</module>
198             <module>drools-applications</module>
199             <module>distribution</module>
200             <module>gui</module>
201             <module>clamp</module>
202         </modules>
203     </project>
204
205 **Policy Architecture/API Transition**
206
207 In Dublin, a new Policy Architecture was introduced. The legacy architecture runs in parallel with the new architecture. It will be deprecated after Frankfurt release.
208 If the developer is only interested in working with the new architecture components, the engine sub-module can be ommitted.
209
210
211 **Step 3:** You can now build the Policy framework.
212
213 Java artifacts only:
214
215     .. code-block:: bash
216
217        cd ~/git/onap
218        mvn clean install
219
220 With docker images:
221
222     .. code-block:: bash
223
224        cd ~/git/onap
225        mvn clean install -P docker
226
227 Developing and Debugging each Policy Component
228 **********************************************
229
230 Running a MariaDb Instance
231 ++++++++++++++++++++++++++
232
233 The Policy Framework requires a MariaDb instance running. The easiest way to do this is to run a docker image locally.
234
235 One example on how to do this is to use the scripts used by the policy/api S3P tests.
236
237 `Simulator Setup Script Example <https://gerrit.onap.org/r/gitweb?p=policy/api.git;a=tree;f=testsuites/stability/src/main/resources/simulatorsetup;h=9038413f67cff2e2a79d6345f198f96ee0c57de1;hb=refs/heads/master>`_
238
239     .. code-block:: bash
240
241        cd ~/git/onap/api/testsuites/stability/src/main/resources/simulatorsetup
242        ./setup_components.sh
243
244 Another example on how to run the MariaDb is using the docker compose file used by the Policy API CSITs:
245
246 `Example Compose Script to run MariaDB <https://gerrit.onap.org/r/gitweb?p=integration/csit.git;a=blob;f=scripts/policy/docker-compose-api.yml;h=e32190f1e6cb6d9b64ddf53a2db2c746723a0c6a;hb=refs/heads/master>`_
247
248 Running the API component standalone
249 +++++++++++++++++++++++++++++++++++++
250
251 Assuming you have successfully built the codebase using the instructions above. The only requirement for the API component to run is a
252 running MariaDb database instance. The easiest way to do this is to run the docker image, please see the mariadb documentation for the latest
253 information on doing so. Once the mariadb is up and running, a configuration file must be provided to the api in order for it to know how to
254 connect to the mariadb. You can locate the default configuration file in the packaging of the api component:
255
256 `Default API Configuration <https://gerrit.onap.org/r/gitweb?p=policy/api.git;a=blob;f=packages/policy-api-tarball/src/main/resources/etc/defaultConfig.json;h=042fb9d54c79ce4dad517e2564636632a8ecc550;hb=refs/heads/master>`_
257
258 You will want to change the fields pertaining to "host", "port" and "databaseUrl" to your local environment settings.
259
260 Running the API component using Docker Compose
261 ++++++++++++++++++++++++++++++++++++++++++++++
262
263 An example of running the api using a docker compose script is located in the Policy Integration CSIT test repository.
264
265 `Policy CSIT API Docker Compose <https://gerrit.onap.org/r/gitweb?p=integration/csit.git;a=blob;f=scripts/policy/docker-compose-api.yml;h=e32190f1e6cb6d9b64ddf53a2db2c746723a0c6a;hb=refs/heads/master>`_
266
267 Running the Smoke Tests
268 ***********************
269
270 The following links contain instructions on how to run the smoke tests. These may be helpful to developers to become
271 familiar with the Policy Framework components and test any local changes.
272
273 .. toctree::
274    :maxdepth: 1
275
276    policy-gui-controlloop-smoke.rst
277    db-migrator-smoke.rst
278    cl-participants-smoke.rst
279    clamp-smoke.rst
280    clamp-cl-participant-protocol-smoke.rst
281    policy-participant-smoke.rst
282    api-smoke.rst
283    pap-smoke.rst
284    apex-smoke.rst
285
286 ..
287    drools-smoke.rst
288
289 ..
290    xacml-smoke.rst
291
292 ..
293    distribution-smoke.rst
294
295
296 Running the Stability/Performance Tests
297 ***************************************
298
299 The following links contain instructions on how to run the S3P Stability and Performance tests. These may be helpful to developers to become
300 familiar with the Policy Framework components and test any local changes.
301
302 .. toctree::
303    :maxdepth: 1
304
305    api-s3p.rst
306    pap-s3p.rst
307    apex-s3p.rst
308    drools-s3p.rst
309    xacml-s3p.rst
310    distribution-s3p.rst
311    clamp-s3p.rst
312
313 Running the Pairwise Tests
314 **************************
315
316 The following links contain instructions on how to run the pairwise tests. These may be helpful to developers check that
317 the Policy Framework works in a full ONAP deployment.
318
319 .. toctree::
320    :maxdepth: 1
321
322    clamp-policy.rst
323
324    clamp-dcae.rst
325
326    policy-cds.rst
327
328 ..
329    api-pairwise.rst
330
331 ..
332    pap-pairwise.rst
333
334 ..
335    apex-pairwise.rst
336
337 ..
338    drools-pairwise.rst
339
340 ..
341    xacml-pairwise.rst
342
343 ..
344    distribution-pairwise.rst
345
346
347 Generating Swagger Documentation
348 ********************************
349 The `Policy Parent Integration POM <https://github.com/onap/policy-parent/blob/master/integration/pom.xml>`_ contains a *generateSwaggerDocs* profile. This
350 profile can be activated on any module that has a Swagger endopint. When active, this profile creates a tarball in Nexus with the name
351 *<project-artifactId>-swagger-docs.tar.gz*. The tarball contains the fillowing files:
352
353 .. code-block:: bash
354
355     swagger/swagger.html
356     swagger/swagger.json
357     swagger/swagger.pdf
358
359 The profile is activated when:
360
361 1. The following property is defined at the top of the *pom.xml* file for a module
362
363     .. code-block:: bash
364
365         <!--  This property triggers generation of the Swagger documents -->
366         <swagger.generation.phase>post-integration-test</swagger.generation.phase>
367
368     See the `CLAMP runtime POM <https://github.com/onap/policy-clamp/blob/master/runtime/pom.xml>`_ for an example of the usage of this property.
369
370 2. Unit tests are being executed in the build, in other wirds when the *skipTests* flag is *false*.
371
372 You **must** create a unit test in your module that generates the following file:
373
374 .. code-block:: bash
375
376     src/test/resources/swagger/swagger.json
377
378 Typically, you do this by starting your REST endpoint in a unit test, issuing a REST call to get the Swagger API documentation. The test case below is an example
379 of such a test case.
380
381 .. code-block:: java
382
383    @Test
384    public void testSwaggerJson() throws Exception {
385        ResponseEntity<String> httpsEntity = getRestTemplate()
386                .getForEntity("https://localhost:" + this.httpsPort + "/restservices/clds/api-doc", String.class);
387        assertThat(httpsEntity.getStatusCode()).isEqualTo(HttpStatus.OK);
388        assertThat(httpsEntity.getBody()).contains("swagger");
389        FileUtils.writeStringToFile(new File("target/swagger/swagger.json"), httpsEntity.getBody(),
390                Charset.defaultCharset());
391    }
392
393 See `this unit test case <https://github.com/onap/policy-clamp/blob/master/runtime/src/test/java/org/onap/policy/clamp/clds/it/HttpsItCase.java>`_
394 for the full example.
395
396 Running the DMaaP Simulator during Development
397 **********************************************
398 It is sometimes convenient to run the DMaaP simulator during development. You can run it from the command line using Maven or from within your IDE.
399
400 Running on the Command Line
401 +++++++++++++++++++++++++++
402 1. Check out the policy models repository
403 2. Go to the *models-sim/policy-models-simulators* subdirectory in the policy-models repo
404 3. Run the following Maven command:
405
406    .. code-block:: bash
407
408       mvn exec:java  -Dexec.mainClass=org.onap.policy.models.simulators.Main -Dexec.args="src/test/resources/simParameters.json"
409
410 Running in Eclipse
411 ++++++++++++++++++
412 1. Check out the policy models repository
413 2. Go to the *models-sim/policy-models-simulators* module in the policy-models repo
414 3. Specify a run configuration using the class *org.onap.policy.models.simulators.Main* as the main class
415 4. Specify an argument of *src/test/resources/simParameters.json* to the run configuration
416 5. Run the configuration
417
418 Specifying a local configuration file
419 +++++++++++++++++++++++++++++++++++++
420
421 You may specify a local configuration file instead of *src/test/resources/simParameters.json* on the command line or as an arument in the run configuration in eclipse:
422
423 .. code-block:: json
424
425    {
426      "dmaapProvider": {
427        "name": "DMaaP simulator",
428        "topicSweepSec": 900
429      },
430      "restServers": [
431        {
432          "name": "DMaaP simulator",
433          "providerClass": "org.onap.policy.models.sim.dmaap.rest.DmaapSimRestControllerV1",
434          "host": "localhost",
435          "port": 3904,
436          "https": false
437        }
438      ]
439    }