Too often teams know what they want to accomplish with Selenium automation but get roadblocked by the infrastructure necessary before they can create their first script. Saunter is an test automation framework removes those roadblocks and says ‘Here; do it like this’.

Saunter‘s partial feature list includes:

  • Designed for Page Objects
  • Sauce Labs integration for cross-browser execution
  • Ready to integrate with your favourite Continuous Integration server
  • Dynamic suite generation using Tags
  • Convenient synchronization helpers
  • Integration with the Browsermob Proxy

Saunter is Open Source and distributed under the Apache License, 2.0. Support and Training are available from Element 34; email for more information.


pip install saunter

As part of the installation, the script is added to the Python installation’s scripts directory. This directory is often included in the OS’s system path.


Being an opinionated framework, once installed the location you will use as your base directory needs to be setup. Py.Saunter takes care of this for you using the –new flag.

saunter --new

This command will create a few of directories and copy the necessary files for the framework to function. It is a non-destructive operation and can be run multiple times.


Emulating a practice popularized by the Ruby-on-Rails community, there are a number of .yaml.default files. Before things will be behave you have to remove the .default part from them. This non-default version will have machine specific information in it and should not be committed to version control. The .default version should however. (Or the .adam, or .production or any other naming convention you come up with — point being, don’t check in the plain .yaml named ones.)

  • You must have at least one file in conf/browsers/. By default, firefox.yaml.default exists. You can name these whatever you like, but the browser they represent makes some degree of sense…
  • The default_browser in saunter.yaml should be the name you chose above.
  • The executor host and port of selenium.yaml points at your Selenium Server
  • Unless you are using Sauce Labs, at which point you need to put your credentials into ‘sauce labs.yaml’ and fill out the OS and version stuff inside the <browser>.yaml file


Saunter distinguishes between Scripts and Page Objects. Think of the difference as Scripts are the What and Page Objects as the How. There will be a lot more detail provided around how to create both of these, but for this, it is important to state that they too have a specific place.

  • Scripts -> scripts/
  • Page Objects -> modules/pages/

Aside from the example projects, these pages also have useful information for creating Scripts and Page Objects.


An important part of Saunter is the use of Tags to generate dynamic execution suites. By default, Saunter will run those scripts which have been tagged as shallow. You can specify different flags by using the -m (marks) flag. For example

saunter -m website

Will run all the scripts discovered in the scripts directory that have been tagged with website.


While Saunter can be run locally on any machine (and should while you are creating your scripts), it is meant to be run inside a Continuous Integration server. To facilitate this, run results are logged in the Ant JUnit format in the logs directory with the most recent one always available as latest.xml. This is the artifact to consume and archive after each run.


Sometimes the easiest way to figure something out is to look at working examples. While the examples are not included in the distribution, there are complete, working Py.Saunter projects online in github.

Class Documentation

There is also auto-generated documentation from the key classes that you will need to interact with available at PyPI


Saunter has been used in a number of large organization in its non-distributed form. There are likely to be a few problem resulting in this new form form of distribution and from more people using it. If you encounter one, don’t be quiet about it. Either