Skip to content

Commit 364785c

Browse files
tbielawatbielawa
committed
Update docs now that we have consistent test targets. RE: US49633
1 parent 410f22b commit 364785c

File tree

7 files changed

+250
-11
lines changed

7 files changed

+250
-11
lines changed

‎Makefile

+1
Original file line numberDiff line numberDiff line change
@@ -49,6 +49,7 @@ help:
4949
clean:
5050
rm -rf $(BUILDDIR)/*
5151
find . -name '*.bak' -delete
52+
@find . -type f \( -name "*~" -or -name "#*" \) -delete
5253

5354
html:
5455
$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html 2>&1 | grep -v 'nonlocal image URI found:'

‎conf.py

+1-1
Original file line numberDiff line numberDiff line change
@@ -79,7 +79,7 @@
7979
# directories to ignore when looking for source files.
8080
exclude_patterns = [
8181
'_build',
82-
'buildstatus.rst',
82+
'development/*.rst',
8383
'intro/components.rst',
8484
# 'components/*.rst',
8585
'intro/definitions.rst',

‎development.rst

+4-2
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,12 @@
11
Development
2-
===========
2+
###########
33
..
44
#.. toctree::
55
# :maxdepth: 1
66
77
.. contents::
88
:local:
99

10-
.. include:: buildstatus.rst
10+
.. include:: development/buildstatus.rst
11+
.. include:: development/contributing.rst
12+
.. include:: development/testing.rst

‎buildstatus.rst renamed to ‎development/buildstatus.rst

+8-8
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,8 @@
11
Build States
2-
------------
2+
************
33

44
RE-CORE
5-
~~~~~~~
5+
+++++++
66

77
Status for the core finite state machine component
88

@@ -12,7 +12,7 @@ Status for the core finite state machine component
1212
----
1313

1414
RE-REST
15-
~~~~~~~
15+
+++++++
1616

1717
Status for the REST endpoint component
1818

@@ -22,7 +22,7 @@ Status for the REST endpoint component
2222
----
2323

2424
RE-WORKER
25-
~~~~~~~~~
25+
+++++++++
2626

2727
Status for the worker component
2828

@@ -32,7 +32,7 @@ Status for the worker component
3232
----
3333

3434
RE-CLIENT
35-
~~~~~~~~~
35+
+++++++++
3636

3737
Status for the client utility component
3838

@@ -42,7 +42,7 @@ Status for the client utility component
4242
----
4343

4444
RE-WORKER-FUNC
45-
~~~~~~~~~~~~~~
45+
++++++++++++++
4646
Worker for executing func calls
4747

4848
.. image:: https://api.travis-ci.org/RHInception/re-worker-func.png
@@ -51,7 +51,7 @@ Worker for executing func calls
5151
----
5252

5353
RE-WORKER-JUICER
54-
~~~~~~~~~~~~~~~~
54+
++++++++++++++++
5555
Worker for executing juicer (rpm promotion) calls
5656

5757
.. image:: https://api.travis-ci.org/RHInception/re-worker-juicer.png
@@ -60,7 +60,7 @@ Worker for executing juicer (rpm promotion) calls
6060
----
6161

6262
RE-WORKER-SLEEP
63-
~~~~~~~~~~~~~~~~
63+
++++++++++++++++
6464
Worker for executing sleeping.
6565

6666
.. image:: https://api.travis-ci.org/RHInception/re-worker-sleep.png

‎development/contributing.rst

+51
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
Contributing
2+
************
3+
4+
This section describes the guidelines for contributing to the Release
5+
Engine.
6+
7+
General Guidelines
8+
++++++++++++++++++
9+
10+
Please conform to :pep:`0008` for code formatting. This specification
11+
outlines the highlights that we require above and beyond. Your code
12+
must follow this (or note why it can't) before patches will be
13+
accepted. There is one consistent exception to this rule:
14+
15+
**E501**
16+
Line too long
17+
18+
The ``pep8`` tests for the Release Engine include a ``--ignore``
19+
option to specifically exclude **E501** from the tests.
20+
21+
22+
Write `unittests
23+
<https://github.com/ashcrow/flagon/tree/master/test>`_ for any new
24+
functionality, `if you are up to the task`. Not a requirement, but it
25+
does get you a lot of karma.
26+
27+
28+
Write `intelligent commit messages
29+
<http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html>`_.
30+
31+
32+
Issue Reporting
33+
+++++++++++++++
34+
35+
If you are reporting an issue with the Release Engine, please use the
36+
following template when describing your issue::
37+
38+
39+
Description of the issue (include full error messages):
40+
41+
How to reproduce the issue:
42+
43+
How reproducable (every time? intermittently?):
44+
45+
Version of the product effected (git hashes are OK):
46+
47+
Your operating system release-version:
48+
49+
What you expected to happen:
50+
51+
What actually happened:

‎development/testing.rst

+183
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,183 @@
1+
Testing
2+
*******
3+
4+
All Release Engine code includes unit tests to verify expected
5+
functionality. In the rest of this section we'll learn how the unit
6+
tests are put together and how to interact with them.
7+
8+
Components
9+
++++++++++
10+
11+
Release Engine unit tests are integrated with/depend on the following
12+
items:
13+
14+
* `Travis CI <https://travis-ci.org/>`_ - Free online service
15+
providing `continuous integration` functionality for open source
16+
projects. Tests are ran automatically on every git commit.
17+
18+
* `unittest <https://docs.python.org/2/library/unittest.html>`_ -
19+
Python unit testing framework. All Release Engine tests are written
20+
using this framework.
21+
22+
* `nose <https://nose.readthedocs.org/en/latest/>`_ - Per the **nose**
23+
website: "`extends unittest to make testing easier`". **nose** is
24+
used to run our unit tests.
25+
26+
* `coverage <http://nedbatchelder.com/code/coverage/>`_ - A tool for
27+
measuring code coverage of Python programs. For the Release Engine
28+
we require a minimum test coverage of **80%**. This is invoked by
29+
**nose** automatically.
30+
31+
* `mock <http://www.voidspace.org.uk/python/mock/>`_ - A library for
32+
testing in Python. It allows you to replace parts of your `system
33+
under test` with mock objects (such as fake REST endpoints) and make
34+
assertions about how they have been used.
35+
36+
* `pep8 <https://pypi.python.org/pypi/pep8>`_ - A tool to check Python
37+
code against some of the style conventions in :pep:`0008`.
38+
39+
* `pyflakes <https://pypi.python.org/pypi/pyflakes>`_ - A simple
40+
program which checks Python source files for errors.
41+
42+
* `Makefiles <http://www.gnu.org/software/make/>`_ - Utility scripts
43+
used for project building and testing. How Release Engine uses
44+
**Makefiles** is described later in this section.
45+
46+
Requirements
47+
++++++++++++
48+
49+
* ``python-nose``
50+
* ``python-coverage``
51+
* ``python-mock``
52+
53+
Some components may have additional test requirements. For example,
54+
:ref:`re-worker-func <re_worker_func>` requires ``pyOpenSSL``, which
55+
requires ``openssl-devel``, ``openssl-libs``, and
56+
``libffi-devel``. Additionally, :ref:`re-rest <re_rest>` requires
57+
``openldap-devel`` to run its unit tests.
58+
59+
.. todo:: Document other test dependencies
60+
61+
62+
Targets
63+
+++++++
64+
65+
In the scope of this document and testing, we use the term `target` in
66+
the context of `makefile targets`. For the purpose of this
67+
documentation, we can think of these `targets` as pre-defined commands
68+
coded in a makefile. Release Engine testing targets include:
69+
70+
* ``ci`` - Run the tests exactly how they are ran in Travis-CI
71+
* ``pep8`` - Run :pep:`0008` syntax checks
72+
* ``pyflakes`` - Run `pyflakes` error checks
73+
* ``clean`` - Remove temporary files and build artifacts from the
74+
checked-out repository.
75+
* ``tests`` - A quicker version of ``ci``. Different from ``ci`` in
76+
that ``tests`` uses libraries installed on the local development
77+
workstation. ``tests`` runs the **unittests**, **pep8** tests, and
78+
**pyflakes** tests automatically.
79+
80+
To ensure the highest degree of confidence in test results you should
81+
always use the ``ci`` target.
82+
83+
When Travis-CI runs an integration test, it calls the ``ci`` target.
84+
85+
Running the Tests
86+
+++++++++++++++++
87+
88+
The Release Engine test suite is invoked via the Makefile. The
89+
following is an example of how to run the ``ci`` test target manually
90+
on the :ref:`re-core <re_core>` component.
91+
92+
93+
.. code-block:: console
94+
:linenos:
95+
:emphasize-lines: 1,29,33
96+
97+
[~/re-core]$ make ci
98+
99+
#############################################
100+
# Creating a virtualenv
101+
#############################################
102+
virtualenv re-coreenv
103+
New python executable in re-coreenv/bin/python
104+
Installing Setuptools..............................................................................................................................................................................................................................done.
105+
Installing Pip.....................................................................................................................................................................................................................................................................................................................................done.
106+
. re-coreenv/bin/activate && pip install -r requirements.txt
107+
Downloading/unpacking pika>=0.9.12 (from -r requirements.txt (line 1))
108+
109+
... snip ...
110+
111+
Successfully installed pep8 nose coverage mock
112+
Cleaning up...
113+
#############################################
114+
# Listing all pip deps
115+
#############################################
116+
. re-coreenv/bin/activate && pip freeze
117+
coverage==3.7.1
118+
mock==1.0.1
119+
nose==1.3.3
120+
pep8==1.5.7
121+
pika==0.9.13
122+
pymongo==2.7.1
123+
wsgiref==0.1.2
124+
#############################################
125+
# Running PEP8 Compliance Tests in virtualenv
126+
#############################################
127+
. re-coreenv/bin/activate && pep8 --ignore=E501,E121,E124 src/recore/
128+
#############################################
129+
# Running Unit Tests in virtualenv
130+
#############################################
131+
. re-coreenv/bin/activate && nosetests -v --with-cover --cover-min-percentage=80 --cover-package=recore test/
132+
Verify using init_amqp provides us with a connection ... ok
133+
Loggers are created with appropriate handlers associated ... ok
134+
135+
... snip ...
136+
137+
Verify create_json_str produces proper json ... ok
138+
Verify load_json_str produces proper structures ... ok
139+
Verify config parsing works as expected. ... ok
140+
141+
Name Stmts Miss Cover Missing
142+
-------------------------------------------------
143+
recore 36 0 100%
144+
recore.amqp 72 4 94% 79, 169-172
145+
recore.constants 1 0 100%
146+
recore.fsm 179 25 86% 97-103, 148-152, 199-249
147+
recore.job 0 0 100%
148+
recore.job.create 25 0 100%
149+
recore.mongo 62 5 92% 92-100
150+
recore.utils 13 0 100%
151+
-------------------------------------------------
152+
TOTAL 388 34 91%
153+
----------------------------------------------------------------------
154+
Ran 35 tests in 0.047s
155+
156+
OK
157+
:
158+
159+
On line **1** we see how to call a makefile target. In this case it's
160+
quite straightforward: ``make ci``. Other targets are called in the
161+
same way. For example, to run the ``clean`` target, you run the
162+
command ``make clean``.
163+
164+
On line **29** we see a header printed, `Running PEP8 Compliance Tests
165+
in virtualenv`. By calling the ``ci`` target, **make** automatically
166+
knows what other targets must be called as well, such as ``ci-pep8``
167+
and ``ci-unittests`` (seen on line **33**).
168+
169+
170+
Troubleshooting
171+
+++++++++++++++
172+
173+
If you find yourself unable to run the unit tests:
174+
175+
#. `Search <https://www.google.com>`_ for relevant error messages
176+
177+
#. **Read** the error message closely. The solution could be hidden in
178+
the error message output. The problem could be as simple as a
179+
missing dependency
180+
181+
#. If you are unable to figure out all the necessary dependencies to
182+
run the tests, file an issue on that specific projects GitHub issue
183+
tracker. Include the full error message.

‎workers/reworkerfunc.rst

+2
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,5 @@
1+
.. _re_worker_func:
2+
13
RE-WORKER-FUNC
24
--------------
35
Release Engine Worker Plugin to run commands over `FUNC <https://fedorahosted.org/func/>`_.

0 commit comments

Comments
 (0)