Doctests

Introduction on testing pyUNO programs with doctests

OpenOffice.org is great, Python is great. Guess what ? PyUNO is great

Scripting OpenOffice.org with Python is an efficient way to produce high quality additional functionalities to your favourite office suite.

But programs has to be tested to ensure reliability and so Python addons and pyUNO scripts. Python comes with various test tools and one of them is doctest.

Here is an example that illustrate a doctest use on a pyUNO script. We have 3 main steps

• start OpenOffice.org in listen mode
• write the doctest
• run the doctest

Starting OpenOffice.org in listen mode

As we plan to use pyUNO for external scripting, we have to start OOo in listen mode as explained in the Developer's guide

 /opt/openoffice.org2.0/program/soffice -accept="socket,host=localhost,port=11111;urp;StarOffice.ServiceManager"

Write the doctest

A doctest is a plain text file mixing comments and Python code from the interpreter. The idea is to write a story, describing what happens while testing. Then we end with both a documentation and a testing program. The idea is to mimic what happens in the Python editor as if we typed directly the command. The expression is evaluated and compared to the given value

a+1 2

If the answer is not 2 while performing the test, it will fail and the error will be reported with the expected value against the current value

Here is a rather long (but not complex) example illustrating some basic OpenOffice.org Python scripting command. A more complete test (dealing also with calc and file export) is provided at the end. These basic commands can be usefull to start dealing with the OpenOffice.org API through pyUNO

We are going to test some basics aspect of Openoffice.org. OOo can be scripted using Python though pyUNO bridge First, we need to import some classical python modules: [python] import uno, unohelper

We will also need some specific services and nammed constants from OpenOffice.org API. They can be imported as any regular python module: [python]

from com.sun.star.connection import NoConnectException
from com.sun.star.beans import PropertyValue
from com.sun.star.text.ControlCharacter import PARAGRAPH_BREAK

This last value is a named constant we will need when dealing with Writer. Let's verify its value: [python]

PARAGRAPH_BREAK

0

Now, we load an helper module that provides some usefull shortcuts whendealing with pyUNO Bridge: [python] from oootools import OOoTools

We now are ready to start our tests. The first action to do is to connect to a listening OOo instance we launched.

Let's define the listening host we have to reach and the port ... [python] HOST = 'localhost' PORT = 11111

We now call out helper connecting class: [python] ooo = OOoTools(HOST, PORT) ctx = ooo.ctx desktop = ooo.desktop

So, we are now connected to the listen OpenOffice.org instance

We open a new blank writer document: [python] doc = desktop.loadComponentFromURL("private:factory/swriter",'_blank',0,()) doc.Text.String

To populate the document, a cursor is needed: [python] cursor = doc.Text.createTextCursor() cursor.ParaStyleName u'Standard'

The default paragraph style is 'Standard', but we plan to write our outline. So we change the ParaStyleName under the cursor: [python] cursor.ParaStyleName = "Heading 1" cursor.ParaStyleName u'Heading 1'

It is now time to insert a first text: [python] doc.Text.insertString(cursor, "Title Level 1", False) doc.Text.String u'Title Level 1'

We insert a paragraph break and some other sentences with various styles: [python] doc.Text.insertControlCharacter(cursor, PARAGRAPH_BREAK, False) cursor.ParaStyleName = "Heading 2" doc.Text.insertString(cursor, "Title Level 2", False) doc.Text.insertControlCharacter(cursor, PARAGRAPH_BREAK, False) doc.Text.insertString(cursor, "A normal sentence !!!", False) doc.Text.String u'Title Level 1\nTitle Level 2\nA normal sentence !!!'

We did not affect any paragraph style for the last sentence, relying on the 'following style' property of the "Heading 2" style. So the paragraph style of this new paragraph should be different: [python] cursor.ParaStyleName == "Heading 2" False cursor.ParaStyleName u'Text body'