How endava/cats works
Overall Project Type and Purpose
• This is a monolithic CLI tool built using Java/Maven.
• Its goal is to generate, execute, and report on API tests using a comprehensive set of “fuzzers” that cover various scenarios.
• It includes modules for reading API contracts (e.g., via OpenAPI), generating test payloads, executing HTTP calls, and reporting results (HTML, JUnit, etc).
Identifying the Main Components
• CLI/Entry Point: Represent the main application (CatsMain) as the starting point. This is where the command line arguments are parsed.
• Command Dispatcher: The command package holds various command implementations (e.g., RunCommand, ListCommand, InfoCommand) directing the application flow.
• Core Engine: This includes the central context (CatsGlobalContext) and configuration (CatsConfiguration) which passes execution parameters across components.
• Fuzzing Modules: Multiple “fuzzer” sub-packages are neatly organized into areas such as:
– Fields Fuzzers (e.g., BaseFieldsFuzzer and its variants organized by type such as leading, trailing, within, only),
– Header Fuzzers (with similar sub-organization),
– HTTP Fuzzers (handling method variations, payload anomalies, etc.),
– Special Fuzzers: handling functional, random, security, or template-based fuzzing.
• DSL Parsing: The DSL packages (e.g., CatsDSLParser, various DSL implementations) handle the parsing of simple non-code syntax provided by the user.
• Generator Modules: Organize generators for data formats (under “generator/format”) and for “simple” generation that produce test payloads and value variations.
• I/O and HTTP Layer: The “io” package encapsulates the ServiceCaller, HTTP handling (which internally may use the forked version of OkHttp) and related utilities.
• Reporting: The reporting module that constructs test reports in various formats (HTML, JUnit, etc.) and monitors execution statistics.
• OpenAPI and Contract Parsing: The “openapi” package and related classes extract API definitions and update test cases as the contract changes.
• Utility/Helper Classes: Shared utilities (e.g., CatsUtil, JsonUtils, VersionChecker, etc.) facilitate cross-module functions.
Relationships and Data Flow
• Start at the CLI/Entry point which routes to a specific command.
• The selected Command interacts with the Global Context and dispatches responsibilities to:
– The Fuzzing Engine: which iterates through available Fuzzers.
– The DSL and Generator modules that dynamically create request payloads, using configuration arguments (found in the args package).
– The HTTP Client (in the io package), which sends test requests.
– The Report Generator, that listens and collates the output into reports.
• External libraries – such as the forked OkHttp and swagger-parser – should be annotated as dependencies within the respective modules (HTTP execution and OpenAPI contract generation).
Architectural Patterns and Design Principles
• Modular design: Different packages/submodules (commands, fuzzers, DSL, generator, reporting) are largely independent, making it easier to extend the tool with new test scenarios.
• Plugin-like extensibility: The fuzzer modules and DSL parsers use polymorphism (abstract/factory patterns evident in the base fuzzer classes) to allow additional strategies without major changes to the core.
• Command pattern: Each CLI command encapsulates its function inside dedicated classes (e.g., RunCommand, LintCommand).
• Clear separation of concerns: There is a distinct separation between generating test cases, executing them, handling HTTP interactions, and reporting.