Sunday, August 18, 2013

Sphinx extension

Sphinx is a tool to provide a special feature for the documentation of a python project. It can used to test snippets in the documentation, to link to another project's documentation, to add links to highlighted source code, to generate autodoc summaries etc. These can be achieved by some of the inbuilt extensions of the sphinx. Sphinx also provide a facility of third party extension in which a user can write an extension for some specific purpose and can upload the extension in sphinx repository.

Understanding the working of sphinx project
Sphinx project is built in several phases.
In phase0, source files are searched from the source directory and initialization of extension takes place. In phase 1, parsing of the source file takes place leading to the formation of doctree(tree formation by the use of docutils). Separate nodes are created for the directives defined in the extension. In phase 2, the doctree is checked for the formation of proper nodes with proper tagname and classes. In phase 3, the temporary nodes created in phase 1 due to improper data are converted in to nodes which can be converted into output using the meta data obtained in phase 2. In phase 4, output is obtained in desired output format.

Steps in designing of sphinx extension
Basically sphinx extension consists of four main components: Directives, Treenodes, Config files and Event handlers.Each extension consists of a setup function which registers all of these components.
Treenodes can be defined by extending the docutil classes defined in docutils.node . These are the nodes of the doctree formed during step 1 of building of sphinx project. Directives can be derived from docutils.parsers.rst.Directives or sphinx.util.compat.Directives . Config files can be used to decide the behavior extension. Finally the event handler does the main function of the extension. There are a lot of phinx APIs which can be used while writing an extension. Those can be found from http://sphinx-doc.org/ext/appapi.html

Tuesday, July 9, 2013

Running robot tests from rst test files

Current rst parser of robotframework recognizes just the test cases in rst format inside the rest files.

To run the text cases in rst files, it has to be first extracted into a separate file and run using text parser.

The extraction can be done by two methods, either by using regex or by using docutils.

In implementation using regex, to detect the literal block, some prefix or suffix needs to be added so that it doesn't consider the statements after the literal blocks used in the statements as test cases.
 eg. in the following statement "Create an example ReST-file with multiple ``.. code:: robotframework``
   -parts and figure out," ".code::robotframework" is the literal block, but  " -parts and figure out," should not be confused with the test case.
Also an indication has to be made to inform that test case has ended.
So while using regex a lot of changes has to be made in the predefined format.

So on the safer side, docutils can be used to bring out the txt test cases. This can be done by forming the doctree using docutils. Then each nodes of  the doctree can be traversed to find if the tagname of the node is the desired literal block. If desired tagname is found at any node, the content of that node can be appended in a temporary file. After the completion of traversal, the temporary file contains all the txt test cases present in the rst file. This temporary file can be run using text parser of robot framework. 

Friday, June 21, 2013

Docutils Structure



DOCUTILS

Docutils is a python docstring processing system. It reads the statements from an input file parses the document and prints the output in a specified format. This is a tool which can be used to process restructured text. The structure of docutils is highly modular and well defined. It has got readers, parsers, transformers and writers.

Reader: Reader understand the input and sends the file to the parser. It sends the file to the parser as a whole or in chucks. If it uses the chuck form, it provides context so the the system can be consolidated again in a single form. It can read normal text format and rest format. It also recognizes FAQs and email.

Parser: It gets the input from the reader and construct document tree from the given input. At present only one parser has been implemented that is rest parser, other parsers are in the way of development.

Transformer: It is related to the formatting of the document tree. It can add to the tree, prune it, change from one form to another and many others. Some transformers are document.Splitter which splits the document into tree structure of sub-documents, document.Merger which combines multiple doctrees into one, parts.Content which generates a table of content for a document etc.

Writer: The writer produces the final output. The output can be in any one of many available formats. Some of the available formats are pdf, HTML, plain text restructured text etc.

Robot Framework test cases


Robotframeworks recognizes some well-defined patterns for it’s test cases. So test data should be entered in these special formats.
Following are the formats known by Robotframework:
n         HTML format
n        TSV format
n        Plain text (.txt) format
n        reStructured text format
HTML format: In HTML format test cases are written in tabular form. It has got separate tables for Settings, Variables, Test Cases and Keywords. The main problem with this format is that the tabular form becomes hectic sometimes as it is not very easy to format tables with normal text readers. In this form everything outside the table is ignored.
Eg
Setting
Value
Value
Value
Library
OperatingSystem







Variable
Value
Value
Value
${MESSAGE}
Hello, world!







Test Case
Action
Argument
Argument
My Test
[Documentation]
Example test


Log
${MESSAGE}


My Keyword
/tmp





Another Test
Should Be Equal
${MESSAGE}
Hello, world!

Keyword
Action
Argument
Argument
My Keyword
[Arguments]
${path}


Directory Should Exist
${path}






TSV format: In TSV format all the data is fed into one table which can be formatted using some spreadsheet programs. The test data are recognized by one or more asterisks followed by a normal table name and an optional closing asterisks. Still it is not preffered to use TSV format over normal text format.
Eg
*Setting*
*Value*
*Value*
*Value*
Library
OperatingSystem










*Variable*
*Value*
*Value*
*Value*
${MESSAGE}
Hello, world!










*Test Case*
*Action*
*Argument*
*Argument*
My Test
[Documentation]
Example test


Log
${MESSAGE}


My Keyword
/tmp





Another Test
Should Be Equal
${MESSAGE}
Hello, world!








*Keyword*
*Action*
*Argument*
*Argument*
My Keyword
[Arguments]
${path}


Directory Should Exist
${path}


Plain text format: This is the most popular data format for robot framework. In this format everything is similar to TSV format except the absence of table. In this content are separated by one or more spaces. This can be very easily edited by any normal text reader. In this the separator is space, so empty cells shouls be entered as ${empty} or /.

Eg 
*** Settings ***
Library       OperatingSystem

*** Variables ***
${MESSAGE}    Hello, world!

*** Test Cases ***
My Test
    [Documentation]    Example test
    Log    ${MESSAGE}
    My Keyword    /tmp

Another Test
    Should Be Equal    ${MESSAGE}    Hello, world!

*** Keywords ***
My Keyword
    [Arguments]    ${path}
    Directory Should Exist    ${path}

Restructured Text format: This is commonly used for the documentation of python projects. In this format simple formatted text is mixed with test tables and the complete file is recognized by robot frameworks. So text cases are embedded in the HTML format in the normal formatted document which are extracted while robot frameworks is parsing through the document. There is a tool called docutils which can easily process the restructured text. At present test cases in normal text format can’t be embedded in the reST file.
Eg
When the is in following format
 =========    ===============    ====================
Settings            Value                             Value
==========    ===============   =====================
Library               Selenium2Library
Test Setup          Open browser              about: browser=firefox
Test Teardown   Close all browsers
===========  ===============   ======================

============           ===================        =================
Test Cases                     Value                                         Value
============            ===================       =================
Plone.org is up              Go to                                          http://www.plone.org/
----------------------          ---------------------------------      ------------------------------
..                                    Capture page Screenshot            plone-org.png
============            ===================       =================

It gets converted by robotframeworks in the following format:
Settings
Value
Value
Library
Selenium2Library

Test Setup
Open browser
about: browser=firefox
Test Teardown
Close all browsers


Test Cases
Value
Value
Plone.org is up
Go to

Capture page Screenshot
plone-org.png

This will now run similar to html test case.