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::