Quickstart

Install

pip install preacher

Preacher is written in Python, published to PyPI and can be installed by pip. This is the most basic way to install Preacher.

There are some requirements to install Preacher by pip due to the dependent packages. If you feel annoyed, see Running on Docker.

• Preacher supports only Python 3.7+.

• Python C headers are required to build C extensions, which are available by installing Python develop packages or installing Python by source code build.

• On Linux, libxml2 and libxslt are required by lxml, as official documentation says.

• jq.py requires autoconf, automake, libtool, make and a C compiler such as gcc.

Unfortunately, Preacher doesn’t support Windows now due to the dependent package jq.py, which cannot be built on Windows.

If you have satisfied environment, let’s install Preacher and see its version. If not, see Running on Docker.

$ pip install preacher
$ preacher-cli --version

Running on Docker

We provide Docker images on Docker Hub to avoid problems caused by environments and dependencies. By default, the container working directory is /work, and the host directory may be mounted here as below.

$ docker pull ymoch/preacher
$ docker run -v $PWD:/work:rw -t ymoch/preacher preacher-cli --version

Verify Your API

First, write your own test scenario. Here is a very simple example of test scenarios.

label: An example of a scenario
cases:
  - label: An example of a case
    request: /path/to/foo
    response:
      status_code: 200
      body:
        - describe: .foo
          should:
            equal: bar

Then, let’s run Preacher to verify your API.

$ preacher-cli -u https://your-server.com/base scenario.yml

Now, you have Preacher test results shown on your console.

Interpret Results

Exit Statuses

When all tests succeeds, preacher-cli command returns 0 as a exit status. When any of tests fails or command fails, it returns not 0. Exit statuses are important for CI automation.

$ echo $?

Verification Statuses

Each verification result has a “Verification Status.”

The List of Verification Statuses

Value	Will Succeed?	Description
SKIPPED	yes	It wasn’t needed to run.
SUCCESS	yes	It was satisfied.
UNSTABLE	no	It wasn’t satisfied.
FAILURE	no	It encountered an unexpected situation and failed.