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.