Sphinx is a Python documentation generator, Robot Framework is a test automation framework. These tools combined make documentation a part of the test coverage. Tests are written in human (customer) readable form and the result documentation contains screenshots from product in development.

1. Sphinx + Robot Framework = documentation as
result of functional testing
Paweł Lewicki
Goldmund, Wyldebeast & Wunderliebe
lewicki@gw20e.com
@plewy

2. ● Tools
● Simple example
● Useful example
Agenda

3. ● reStructured text
● Python documentation generator
● Pluggable
● Different outputs
● Standard in Python world
Tools: Sphinx

4. Tools: Robot Framework
● Tests automation framework
● tool for acceptance test-driven development
● keyword-driven testing approach
● Web testing with Selenium2 library
o headless with PhantomJS

5. *** Variables ***
${LOGIN_URL} https://www.python.org/accounts/login/
${HOME_URL} https://www.python.org
*** Keywords ***
Open Browser To Login Page
Open Browser ${LOGIN URL}
Maximize Browser Window
Title Should Be Sign In to Python.org
test.robot(1/2)

6. *** Test Cases ***
Valid Login
Open Browser To Login Page
Input Text id_login demouser
Input Text id_password demopass
Click button css=.primaryAction
Location Should Be ${HOME_URL}
Page Should Contain demouser
Title Should Be Welcome To Python.org
[Teardown] Close Browser
test.robot(2/2)

7. Keywords - selenium2
● “Add Cookie”
● “Click Button/Image/Link”
● “Drag And Drop”
● “Element Should Contain”
● “Input Password”
● “Mouse Down”
● “Radio Button Should Be Set To”
● “Set Window Size”

8. Keywords - selenium2screenshots
● “Add pointy note”
● “Remove element”
● “Update element style”
● “Align elements horizontally”
● “Capture viewport screenshot”
● “Crop page screenshot”
● jQuery based functions

9. ● buildout created with zc.buildout
● Fixture of Sphinx documentation
● reST code enriched with Robot Framework
Minimal setup

10. [buildout]
parts = sphinx-build
[sphinx-build]
recipe = zc.recipe.egg
eggs =
Sphinx
sphinxcontrib-robotframework [docs]
sphinx-rtd-theme
scripts =
sphinx-build
# Usage:
# bin/sphinx-build -b html docs build
Minimal setup
Minimal setup:
buildout.cfg

11. +---desktop
---_screenshots
---index.rst
+---tablet
---_screenshots
---index.rst
+---mobile
---_screenshots
---index.rst
conf.py
index.rst
robot.rst
_frontpage.rst
_topmenu.rst
Minimal setup: docs/

12. ==========================
PyGrunn site documentation
==========================
.. include:: robot.rst
.. toctree::
:maxdepth: 2
:numbered:
desktop/index
tablet/index
mobile/index
docs/: index.rst

13. .. code:: robotframework
*** Settings ***
Resource Selenium2Screenshots/keywords.robot
*** Variables ***
${BASE_URL} = http://pygrunn.org
*** Keywords ***
Suite Teardown
Close All Browsers
docs/: robot.rst

14. Tablet (768x)
===============
.. code:: robotframework
… (cut part)
*** Keywords ***
Suite Setup
Open Browser ${BASE_URL}
Set window size 768 900
*** Test Cases ***
.. include:: ../_frontpage.rst
.. include:: ../_topmenu.rst
docs/: tablet/index.rst

15. Initial viewport
----------------
Below we can see the screenshot taken from current pyGrunn.org site.
.. figure:: _screenshots/homepage.png
.. code:: robotframework
Site homepage viewport
Go to ${BASE_URL}
Capture viewport screenshot _screenshots/homepage.png
docs/: _frontpage.rst

16. $bin/sphinx-build -b html docs build
…and…

19. Cropping and annotations
------------------------
Below we may see cropped and annotated page element.
.. figure:: _screenshots/topmenu.png
.. code:: robotframework
Capture annotated top menu
${note1} = Add pointy note
... css=.headerbar
... This Robot Framework stuff is very very cool!
... width=200 position=bottom
Capture and crop page screenshot _screenshots/topmenu.png
... css=.headerbar ${note1}
docs/: topmenu.rst

21. Useful example
● Plone theme product
● Documentation as part of testing
● Jenkins as visual regression tester

22. Plone product (package/egg)
● plone.app.testing
o fixture of fully working Plone site
● plone.app.robotframework
o Plone-related keywords

23. Plone setup: testing.py
from plone.app.testing import FunctionalTesting
from plone.app.robotframework.testing import REMOTE_LIBRARY_BUNDLE_FIXTURE
EXAMPLE_THEME_ROBOT_TESTING = FunctionalTesting(
bases=(EXAMPLE_THEME_ACCEPTANCE_FIXTURE,
REMOTE_LIBRARY_BUNDLE_FIXTURE,
z2.ZSERVER_FIXTURE),
name="ExamplethemeLayer:Robot"
)
$bin/robot-server example.theme.testing.EXAMPLE_THEME_ROBOT_TESTING

24. Edit document
.............
.. figure:: _screenshots/document-edit.png
.. code:: robotframework
Capture Document Edit Screenshot
${uid} = Create content type=Document
... id=new-document
... title=${DUMMY_TEXT_LINE}
... description=${DUMMY_TEXT_SHORT} text=${DUMMY_TEXT}
Fire transition ${uid} publish
Go to ${PLONE_URL}/new-document/edit
Capture page screenshot _screenshots/document-edit.png
Plone setup: Robot
content creation

25. Keywords -
plone.app.robotframework
● “Debug”
● “Log in as test user”
● “Trigger Workflow Transition”
● “Add content”
● “Click Action by id”

26. ● Git repository
● Bash script
virtualenv .
bin/pip install distribute
bin/python bootstrap.py
bin/buildout
bin/test
bin/sphinx-build -b html docs build
● Documentation (build/index.html)
Jenkins setup

29. Useful areas
● Customer documentation
● Visual coverage of theme development
o commit hooks trigger new version
● Multiple versions
o Screen sizes (responsiveness)
o Language versions
 http://www.youtube.com/watch?v=VN9FROZO5AY
o the same application many themes
● FUNCTIONAL TESTING

30. References
● https://github.com/lewicki/pygrunn_robot_demo

31. Thank you!
Questions?
Paweł Lewicki
Goldmund, Wyldebeast & Wunderliebe
lewicki@gw20e.com
@plewy