Pylatest Document Types¶
This is an overview of document types supported by Pylatest. For each type, Pylatest expects particular structure of rst file, list of directives and roles which could be used and so on. Some rules described there are required for some pylatest features to work, in other cases it’s just matter of convention.
Test Case¶
The main Pylatest document type. The rst file of a test case has to follow structure as described below.
Test Case Title¶
Main heading with document title represents a title of a test case, eg.:
Test Case Title
***************
This title is mandatory.
Test Case Metadata¶
Just after document title, there is a docutils field list with test case metadata, eg.:
:author: someone@example.com
:component: foo
:subcomponent: bar
:priority: high
Field names of metadata specified here (author
, component
, …) don’t
have to follow any convention, with an exception of requirements.
To specify requirement covered by a test case, you need to use either
requirement
or requirements
as a field name in this section, eg:
:requirement: FOO-123
To specify multiple requirements, you can use a list like this:
:requirements:
- FOO-123
- FOO-171
It’s recommended to reference requirements by url:
:requirement: https://example.com/foo-123
Or via rhbz
role, if there is a bugzilla for it, eg:
:requirement: :rhbz:`439858`
Test Case Description¶
Description of a test case is represented by dedicated section with title Description, eg.:
Description
===========
This is just demonstration of usage of pylatest
rst directives and expected structure of rst
document.
Test Case Setup and Teardown¶
There is one section for test setup, and another one for teardown.
In both sections, setup or teardown steps are written down via enumerated list, eg.:
Setup
=====
#. This is a first step of the setup.
#. There is another one.
Test Steps¶
Section Test Steps contains list of test steps and expected results, written
down using test_action
directive.
Test Steps
==========
.. test_action::
:step: List files in the volume: ``ls -a /mnt/helloworld``
:result: There are no files, output should be empty.
Also note that when the description of a test step is long and/or complicated, you can use multiple paragraphs to describe it as shown in the example.
.. test_action::
:step:
Run the following commands::
$ foo --extra sth
$ bar -vvv
And wait at least 10 seconds.
:result:
Maecenas congue ligula ac quam viverra nec
consectetur ante hendrerit.
This section is mandatory.
Full Example¶
Here is full example of a test case document based the conventions described above:
Test Case Title
***************
:author: someone@example.com
:component: foo
:subcomponent: bar
:priority: high
:requirement: https://example.com/foo-123
Description
===========
This is just demonstration of usage of pylatest
rst directives and expected structure of rst
document.
Setup
=====
#. This is a first step of the setup.
#. There is another one.
Test Steps
==========
.. test_action::
:step: List files in the volume: ``ls -a /mnt/helloworld``
:result: There are no files, output should be empty.
.. test_action::
:step:
Run the following commands::
$ foo --extra sth
$ bar -vvv
And wait at least 10 seconds.
:result:
Maecenas congue ligula ac quam viverra nec
consectetur ante hendrerit.
Teardown
========
#. Description of the cleanup.
Index¶
Index file (usually named index.rst
) represents all test cases placed in
the same directory as the index file.
Subdirectories with index file could be used to group test cases together and
enforce particular metadata on the whole group via test_defaults
directive.
Usual use case is to create subdirectory with index.rst
file for particular
component like this:
Foo Component
=============
.. test_defaults::
:component: foo
.. toctree::
:caption: Test Cases
:maxdepth: 1
:glob:
test_*
So that html build of index file will contain list of all test cases there
and enforce particular value of :component:
metadata on all test cases
at the same time.
List of requirements¶
This document provides an overview of all requirements covered by all test cases in Sphinx/Pylatest project.
The list itself is generated by requirementlist
directive.
The expected use case is to generate an overview of requirements for all test cases like in the following example:
Requirements
============
Overview of all requirements covered by test cases.
.. requirementlist::