Home

Awesome

<p align="center"> <picture> <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/Endava/cats/master/images/cats_logo_dark.svg" /> <img alt="CATS logo" src="https://raw.githubusercontent.com/Endava/cats/master/images/cats_logo_light.svg" width="400"> </picture> </p> <p align="center">

CI Commits

Quality Gate Status Technical Debt Coverage Bugs Code Smells

</p>

CATS documentation is available at https://endava.github.io/cats/

REST API fuzzer and negative testing tool. Run thousands of self-healing API tests within minutes with no coding effort!

<p align="center"></p>

Short on time? Check out the 1-minute Quick Start Guide!

Overview

By using a simple and minimal syntax, with a flat learning curve, CATS (Contract API Testing and Security) enables you to generate thousands of API tests within minutes with no coding effort. All tests are generated, run and reported automatically based on a pre-defined set of 100+ Fuzzers. The Fuzzers cover a wide range of boundary testing and negative scenarios from fully random large Unicode values to well crafted, context dependant values based on the request data types and constraints. Even more, you can leverage the fact that CATS generates request payloads dynamically and write simple end-to-end functional tests.

HTML Report

<div align="center"> <img alt="CATS" width="100%" src="images/tests_result.png"/> </div>

Command Line

<div align="center"> <img alt="CATS" width="100%" src="images/run_result.png"/> </div>

Tutorials on how to use CATS

This is a list of articles with step-by-step guides on how to use CATS:

Some bugs found by CATS

Installation

Homebrew

> brew tap endava/tap
> brew install cats

Manual

CATS is bundled both as an executable JAR or a native binary. The native binaries do not need Java installed.

After downloading your OS native binary, you can add it to PATH so that you can execute it as any other command line tool:

sudo cp cats /usr/local/bin/cats

You can also get autocomplete by downloading the cats_autocomplete script and do:

source cats_autocomplete

To get persistent autocomplete, add the above line in .zshrc or .bashrc, but make sure you put the fully qualified path for the cats_autocomplete script.

You can also check the cats_autocomplete source for alternative setup.

There is no native binary for Windows, but you can use the uberjar version. This requires Java 21+ to be installed.

You can run it as java -jar cats.jar.

Head to the releases page to download the latest version: https://github.com/Endava/cats/releases.

Build from sources

You can build CATS from sources on you local box. You need Java 21+. Maven is already bundled.

Before running the first build, please make sure you do a ./mvnw clean. CATS uses a fork of OKHttp which will install locally under the 4.11.0-CATS version, so don't worry about overriding the official versions.

You can use the following Maven command to build the project as an uberjar:

./mvnw package -Dquarkus.package.type=uber-jar

You will end up with a cats-runner.jar in the target folder. You can run it wih java -jar cats-runner.jar ....

You can also build native images using a GraalVM Java version.

./mvnw package -Pnative

Notes on Unit Tests

You may see some error log messages while running the Unit Tests. Those are expected behaviour for testing the negative scenarios of the Fuzzers.

Experimental: Maven dependency for programmatic use

CATS doesn't have explicit support (yet) for programmatic use via JUnit or TestNG. You can however experiment with running the CatsMain class with the same arguments as you would run in the command line.

You must add these 2 dependencies:

<dependency>
    <groupId>com.squareup.okhttp3</groupId>
    <artifactId>okhttp</artifactId>
    <version>4.11.0</version>
</dependency>
<dependency>
    <groupId>com.endava</groupId>
    <artifactId>cats</artifactId>
    <version>9.0.3</version>
</dependency>

Please not that you also need to explicitly add the okhttp dependency. CATS uses a fork of okhttp that is not published in Maven central. When using CATS as a dependency, HTTP header fuzzers that prefix/suffix header values with spaces won't properly work.

Contributing

Please refer to CONTRIBUTING.md.