Hitch Command Line Interface


This documentation applies to the latest version of hitch and hitchtest.

hitch init

If not already initialized, running:

$ hitch init

Will do the following:

  • Create a .hitch directory
  • Check for and ask you to install the following system packages: python-dev, python3-dev, libtool, automake, cmake (or equivalents).
  • Check that the system packages specified in the file system.packages are installed. Attempt to install them if not.
  • Installs all hitch plugin packages specified in hitchreqs.txt.
  • Ask you to install any system packages required by plugins and not already installed.

If already initialized, hitch init will:

  • Install any package versions specified in hitchreqs.txt but not installed in your environment.
  • Verify again that all required system packages from system packages, hitch plugins.

You should run this command whenever hitchreqs.txt is changed (for example if you do a git pull).


If you are running tests in a continuous integration environment, you should ensure that hitch init is run before every test run and that the user it is run as has passwordless sudo.

You should also run hitch init on your development environment if somebody else changes your hitchreqs.txt.

hitch test [ tests ]

To run a specific .test file:

$ hitch test stub.test

To run all of the tests in a directory (and its subdirectories), e.g.:

$ hitch test .

You can also specify multiple files and directories to test, e.g.:

$ hitch test apptests/ apitests/ stub.test

hitch test [ tests ] –tags

To only run tests that match specified tags, you can use the –tag switch to specify the tests you want to run:

$ hitch test . --tags tag1,tag2,tag3

hitch test [ tests ] –settings

You will at some point want to run the same tests in different environments. This is what hitch settings are for.

To use a different settings file, you can use the –settings switch to specify the settings file to use. For example, for a continuous integration environment you might run:

$ hitch test . --settings ci.settings

Whereas in your test driven development environment you might run:

$ hitch test . --settings tdd.settings

These commands will ensure that your tests are run with settings from both all.settings and the YAML settings file specified on the command line.

You can also specify settings using JSON on the command line by using the –extra switch, e.g.:

$ hitch test . --settings ci.settings --extra '{"failfast":true}'

For more about settings and configuration see Settings

hitch test [ tests ] –yaml

If you are using Jinja2 to parameterize your tests, you may want to just display the YAML generated by it to check that your jinja2 has no problems and is templating your tests correctly.

You can do that using the –yaml switch:

$ hitch test simple_reminder.test --yaml

hitch install

Once you have an environment set up, you can install hitch plugin packages to test different kinds of things. For example:

$ hitch install hitchselenium

This will install the hitch plugin package responsible for testing web applications with the firefox browser and selenium.

Hitch install will do the following when you run ‘hitch install’:

  • Download the hitch plugin package from pypi and install it in your environment.
  • Update hitchreqs.txt with the plugin package as well as any packages it depends upon.
  • Attempt to install any system packages required by the plugin package. For instance, hitchselenium needs firefox and xvfb.


Note that hitch plugin packages are just regular python packages downloaded from pypi. Running this command is roughly equivalent to running pip install.

If you want to install any other python packages to use with your engine.py, you can use this command.

hitch uninstall

This lets you uninstall plugin packages from your environment. For example:

$ hitch uninstall hitchselenium

It will also update hitchreqs.txt afterwards.

hitch upgrade

See : How to upgrade Hitch

This command will upgrade all of the plugins installed in your hitch directory and save all of their newly fixed versions to hitchreqs.txt.

hitch clean

This command removes the .hitch folder. It is a good idea to run this command and run hitch init after if you suspect your .hitch directory might have been corrupted.

hitch cleanpkg

This command removes the ~/.hitchpkg folder, which contains all of the hitch packages downloaded, compiled and installed in order to run tests.

It is a good idea to run this command and re-run your tests after if you suspect your ~/.hitchpkg may have been corrupted.