Skip to content
microservices test and univeral migrations tool
Branch: master
Clone or download
Latest commit 1cb67fd Jun 30, 2019


Microservices automated test tool

Support your team with a good Catcher!

What is catcher?

Catcher is a flexible tool, that can be used for: automated end-to-end testing, running universal migrations, performing complex business actions. It helps you to check either one service or whole system interaction. With the help of Catcher you can easily mock external services your system relies on. Catcher is not about only http, it can check Kafka, Postgres, CouchBase, Mongodb.

Testing - How it works?

  1. You implement new business requirements, touching one ore more services (external and internal)
  2. You write tests file in YAML or JSON formats where you describe data movement in your system
  3. You run your tests in any environment (from dev to prod) just changing inventory files.
  4. Bob (your colleague) implements his own business logic, which requires your test (or part of it) to be run.
  5. Bob writes his test in YAML and includes your test (or certain steps) to be run before or during his test.
  6. John (your devOps) decides to automate tests and makes CI run all tests on every microservice deploy.
  7. Your business logic is tested automatically and you will know if some of your services interact incorrectly.
  8. Profit.

Migration - How it works?

Every new feature in microservices require several migration steps in more than one service. But it is much better to create one migration script for all services (kafka, aws, databases) to prevent code duplication and keep all instructions in one place. See more in migrations

Complex business actions - How it works?

If in your company you need to perform some complex business actions - use catcher to automate them.
F.e. before business review you need to register a new user and it requires you to make 10 http request and send 2 kafka messages.
Do you really like to spend 10-20 minutes of your time on doing these steps one by one?
Write a catcher script register_new_user.yaml and call it manually:
catcher -i inventory.yaml register_new_user.yaml -e user_name=test_22.04.2018.


To install catcher with all internal modules run sudo pip install catcher-modules[all].
This will install catcher and catcher-modules package.
To install just catcher run sudo pip install catcher.
To install specific catcher-module use pip install catcher-modules[kafka]. See catcher-modules-index for all available modules.

New in 1.19.0:

To have docker-compose support install catcher[compose] instead.
This will make catcher run docker-compose up in your resources directory, if docker-compose file was found.


  • Write catcher script (see tests). F.e.:

    - http: {get: {url: ''}}
    - redis:
            get: 'foo'
        register: {foo: '{{ OUTPUT }}'}
    - check:
        equals: {the: '{{ foo }}', is: 'bar'}
  • Run catcher catcher my_test_file.yml.

You can also specify inventory with -i to test against different environments, custom module paths with -m to include your own modules. Run catcher -h to get full list of available options.

Why catcher?

  • don't repeat test code. Write one test and call its steps from another;
  • compute and override variables to check your data and compose new flexible requests;
  • apply :meth:`catcher.steps.check` to the steps results;
  • write test for development, change inventory and test stage/uat/prod after deploy;
  • test all your microservices with ease;
  • automate your testing!
  • modular architecture

Quickstart and documentation

See readthedocs.

You can’t perform that action at this time.