From a278cfed0faa597d1d6c38be8586d04b1bfe11eb Mon Sep 17 00:00:00 2001 From: Seenivasan Gunabalan Date: Thu, 10 Nov 2016 14:24:48 +0530 Subject: [PATCH] Added developer documentation This commit contains 'how to do' documents for creating new flavor criteria plugin and writing funcitonal test cases. Change-Id: I1268e804cbf3493058599b014f7e8b0378444440 Closes-bug: #1639731 --- doc/source/developer-guide/add_new_api.rst | 111 ++++++++++++++++++ .../add_new_functional_testing.rst | 83 +++++++++++++ doc/source/developer-guide/deploy.rst | 29 +++++ doc/source/index.rst | 7 ++ 4 files changed, 230 insertions(+) create mode 100644 doc/source/developer-guide/add_new_api.rst create mode 100644 doc/source/developer-guide/add_new_functional_testing.rst create mode 100644 doc/source/developer-guide/deploy.rst diff --git a/doc/source/developer-guide/add_new_api.rst b/doc/source/developer-guide/add_new_api.rst new file mode 100644 index 0000000..7626309 --- /dev/null +++ b/doc/source/developer-guide/add_new_api.rst @@ -0,0 +1,111 @@ +.. _add_new_api: + Copyright 2016 Intel Corporation + All Rights Reserved. + + Licensed under the Apache License, Version 2.0 (the "License"); you may + not use this file except in compliance with the License. You may obtain + a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, WITHOUT + WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the + License for the specific language governing permissions and limitations + under the License. + +================================= +Add a new API endpoint in Valence +================================= + +In this Guide, you will find information on how to add new API in to Valence. +This guide assumes that Valence environment is already setup (if not please go +through the `readme.rst`). + + +Interacting with Valence +------------------------- + +Before starting modification/adding a new functionality in Valence, it is suggested +to check that the valence has been setup properly. This could be done by making some +REST calls to the existing APIs and verifying their response. + +.. NOTE:: + + curl or some other GUI REST clients(like Postman plugin for Chrome browser) + could be used for making the REST calls. + + .. code-block:: bash + + $ curl http://localhost:8181/v1 + +The above REST API call will return a json with valence version specific details. This +ensure that Valence has been setup rightly. + + +Example 'Hello World' API implementation +---------------------------------------- + +Consider we want to implement a new API /v1/example that returns "hello world" json. + +#. Create a python module inside api/v1 directory that + handles the API call + + .. code-block:: python + + #valence/api/v1/example.py + + from flask import request + from flask_restful import Resource + import logging + + LOG = logging.getLogger(__name__) + + class Example(Resorce): + def get(self): + LOG.debug("GET /example") + return {“msg” : “hello world”} + + .. note:: Check the valence/common/utils.py for commonly used functions + and valence/common/exceptions.py for valence structured + errors and standard confirmation messages. + +#. Add a new route at 'routes.py' to receive requests at particular URL extension + + .. code-block:: python + + from valence.api.v1.example import Example + ... + ... + api.add_resource(Example, '/v1/example', + endpoint='example') + +#. Start/Restart the valence server + + .. code-block:: bash + + $ python -m valence.cmd.api + + .. note:: Ensure config(/etc/valence/valence.conf) and + log(/var/log/valence/valence.log) files exists. + + +#. Test the service manually by issuing a GET request to /v1/example + + .. code-block:: bash + + $ curl http://localhost:8181/v1/example + + +#. Run tox testing to check pep8 and python2.7 compatibility. This + should be ran from the valence root directory(where tox.ini is + present) + + .. code-block:: bash + + $ tox -e pep8,py27 + + +#. Update the automated testing scripts to include the new API. + .. include:: add_new_functional_testing.rst + diff --git a/doc/source/developer-guide/add_new_functional_testing.rst b/doc/source/developer-guide/add_new_functional_testing.rst new file mode 100644 index 0000000..6760743 --- /dev/null +++ b/doc/source/developer-guide/add_new_functional_testing.rst @@ -0,0 +1,83 @@ +.. _valence_functional_testcase: + Copyright 2016 Intel Corporation + All Rights Reserved. + + Licensed under the Apache License, Version 2.0 (the "License"); you may + not use this file except in compliance with the License. You may obtain + a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, WITHOUT + WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the + License for the specific language governing permissions and limitations + under the License. + +============================ +Addng a Functional Test case +============================ + +Getting used to writing testing code and running this code in parallel is considered +as a good workflow. +Whenever an API for valence is implemented, it is necessary to include +the corresponding testcase in the testing framework. +Currently, valence uses pythons unittest module for running the testcases. + +Tests scripts are located in `/valence/tests +`_ directory + +.. NOTE:: + valence/tests/__init__.py contains the base class for FunctionalTest + + +Implementing a Test Case +------------------------ + +Consider implementing an functional testcase for our /example(add_new_api_) API + + +The characteristics of /example(add_new_api_) API + +* REST Method : GET +* Parameters : Nil +* Expected Response Status : 200 +* Expected Response JSON : {“msg” : “hello world”} + +To implement a testcase for the /example api, + +Create a class in valence/tests/functional/test_functional.py +which inherits the FunctionalTest class from valence/tests/__init__.py +i.e. + + .. code-block:: python + + # valence/tests/functional/test_functional.py + + class TestExampleController(FunctionalTest): + + def test_example_get(self): + response = self.app.get('/example') + #Call GET method of /example from Flask APP + #If REST call went fine, we expect HTTP STATUS 200 along with JSON + assert response.status_code == 200 + #Test the status + assert response["msg"] == "hello world" + #Test the response message + #likely we could test headers for content-type..etc + + def test_example_post(self): + #suppose consider if POST is implemented & returns STATUS 201 + response = self.app.post('/example') + assert response.status_code == 201 + +The above is a very basic example which could be extended to test complex JSONs +and response headers. + +Also for every new code added, it is better to do pep8 and other python automated +syntax checks. As we have tox integrated in to valence, this could be achieved by, +running the below command from the valence root directory(where tox.ini is present) + + .. code-block:: bash + + $ tox -e pep8,py27 diff --git a/doc/source/developer-guide/deploy.rst b/doc/source/developer-guide/deploy.rst new file mode 100644 index 0000000..086fe2d --- /dev/null +++ b/doc/source/developer-guide/deploy.rst @@ -0,0 +1,29 @@ +.. _valence_deploy: + + Copyright 2016 Intel Corporation + All Rights Reserved. + + Licensed under the Apache License, Version 2.0 (the "License"); you may + not use this file except in compliance with the License. You may obtain + a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, WITHOUT + WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the + License for the specific language governing permissions and limitations + under the License. + + +This document describes how to update the code base of Valence after installation. +Whenever valence code has been updated, either through git or modifying it locally, +it needs to be deployed to standard python path. The below steps describes them. + +Execure the below bash commands in the valence root directory +(where the setup.py file exists) + + .. code-block:: bash + + $ python setup.py install + $ sudo service valence restart diff --git a/doc/source/index.rst b/doc/source/index.rst index a048ef7..e780f1f 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -16,6 +16,13 @@ Contents: usage contributing +Developers Documentation +======================== +.. toctree:: + :maxdepth: 2 + + developer-guide/* + Indices and tables ==================