# APIVERITAS
A CLI tool for consumer-driven contract testing using JSON comparisons.
[](https://github.com/mariogalea/qualitymatters-apiveritas/actions/workflows/ci_github_actions.yml/badge.svg)
[](https://github.com/mariogalea/qualitymatters-apiveritas)
**APIVERITAS** — Because your endpoints shouldn’t gaslight your frontend.
A lightweight, CI-friendly contract testing tool for RESTful APIs. APIVERITAS ensures that your API responses stay consistent, honest, and predictable across environments and deployments.
## Feature Highlights
- **Schema Validation**
Validate API responses against strict or flexible JSON Schemas to ensure structural integrity and type correctness.
- **Payload Comparison**
Compare live (production/dev) API responses against baseline payloads to detect unexpected changes and regressions.
- **Configurable Test Suites**
Customize behavior using a `config.json` file — control schema strictness, mock server usage, report paths, and more.
- **HTML Reporting**
Generate clear, collapsible, and human-readable HTML reports with inline diffs for easy debugging.
- **CI/CD Integration**
Designed to plug seamlessly into your CI pipelines — fail builds when contracts are broken, and track API integrity over time.
- **Clean Architecture**
Built with modular, object-oriented TypeScript for extensibility, maintainability, and clean separation of concerns.
- **Mock Server Support**
Use an optional mock server with predefined responses for testing in isolated or offline environments — ideal for CI and sandbox testing.
## Installation
APIVERITAS can be installed in different ways - either globally or locally.
### Global Installation
To install APIVERITAS globally:
```bash
npm install -g apiveritas
```
#### Why use `-g`?
Using the `-g` flag installs APIVERITAS globally, making the `apiveritas` command available from anywhere on your system. This is useful when:
- You want to run the CLI across multiple projects.
- You're integrating it into global workflows or CI/CD pipelines.
- You prefer not to manage a local dependency for every individual project.
Global installation provides convenience and consistency, especially for tools designed to work across repositories or environments.
### Local Installation
You can also install APIVERITAS as a local development dependency:
```bash
npm install --save-dev apiveritas
```
#### Why use `--save-dev`?
- You want tighter version control per project.
- You prefer not to install the CLI globally.
- You're sharing the project with collaborators or CI systems that use npm ci
## Usage
ApiVeritas provides a straightforward CLI with commands to manage and validate your API contracts efficiently.
You can run commands to execute tests, generate reports, manage payload snapshots, and configure your testing environment. Each command is designed to integrate seamlessly into your development workflow and CI/CD pipelines.
Below are the primary CLI commands you’ll use to get started and maintain API contract integrity.
```bash
Usage: apiveritas [options] [command]
A lightweight CLI tool for API contract testing
Options:
-V, --version output the version number
-h, --help display help for command
Commands:
test [options] Run all API requests and save responses
list-tests List all available JSON test files in the tests/ folder
payloads-path Show where the payloads are stored
reports-path Show where HTML reports are stored
config Show current configuration loaded from config.json
set-config [options] Update one or more config values
compare [options] Compare the two most recent payload folders and show test results
run [options] Run tests, compare payloads, and report results
notest A little surprise inspired by Pulp Fiction
help [command] display help for command
```
### test
Run all API requests defined in a test suite JSON file and save the responses.
```bash
apiveritas test --tests
```
Example:
```bash
apiveritas test --tests bookings.json
```
*If mock server mode is enabled, the test suite will default to `mock.json`.
### list-tests
List all available JSON test files in the `tests/` directory.
```bash
apiveritas list-tests
```
### payloads-path
Show the current path where payloads are stored.
```bash
apiveritas payloads-path
```
### reports-path
Show the current path where HTML reports are stored.
```bash
apiveritas reports-path
```
### config
Display the current loaded configuration from `config.json`.
```bash
apiveritas config
```
### set-config
Update configuration values interactively or via flags.
Options:
- `--strictSchema `
- `--strictValues `
- `--tolerateEmptyResponses `
- `--payloadsPath `
- `--reportsPath `
- `--baseUrl `
- `--enableMockServer `
#### Configuration Flags
- `--strictSchema `
Enforce strict JSON schema validation. When `true`, any deviation from the defined schema will cause the test to fail. When `false`, added json properties are permitted (missing ones will fail the comparison test).
- `--strictValues `
Enforce strict value matching. When `true`, differences in response values (beyond schema) will cause test failures.
- `--tolerateEmptyResponses `
Allow empty API responses without failing the test. Useful when some endpoints may legitimately return empty payloads.
- `--payloadsPath `
Shows the directory path where API response payloads are stored for comparison and reference.
- `--reportsPath `
Shows the directory path where HTML test reports are saved after comparison runs.
- `--baseUrl `
Define the base URL of the API server to be tested.
- `--enableMockServer `
Enable or disable the internal mock server. When `true`, tests use mock responses instead of hitting a live API.
Example:
```bash
apiveritas set-config --strictSchema true --baseUrl http://localhost:8080
```
### compare
Compare the two most recent payload folders for a given test suite and report differences.
```bash
apiveritas compare --testSuite
```
Example:
```bash
apiveritas compare --testSuite bookings
```
### run
Run a full workflow: execute API calls, save responses, and compare the latest payload folders.
```bash
apiveritas run --tests --testSuite
```
Example:
```bash
apiveritas run --tests bookings.json --testSuite bookings
```
*If mock server mode is enabled, the test suite will default to `mock.json`, targeting base url http://localhost:3000
### notest
A fun easter egg inspired by *Pulp Fiction*.
```bash
apiveritas notest
```
## Mock Server Mode
When enabled (`enableMockServer: true`), ApiVeritas runs an internal mock server and uses `mock.json` test suite by default. This allows testing without a live API.
## ✅ CI Setup Snippet (GitHub Actions)
```yaml
name: CI
on:
push:
branches: [ main ]
jobs:
verify-contracts:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v3
- name: Setup Node.js
uses: actions/setup-node@v4
with:
node-version: '20'
- name: Install dependencies
run: npm ci
- name: Install ApiVeritas globally
run: npm install -g .
- name: Run contract tests
run: apiveritas run --tests mock.json --testSuite mock
```
## Exit Codes
APIVERITAS uses the following exit codes to indicate the result of CLI operations. This helps with scripting, CI pipelines, and automated monitoring.
| Exit Code | Meaning |
|-----------|-------------------------------------------|
| 0 | Success |
| 1 | General error (unexpected) |
| 2 | Missing or invalid arguments |
| 3 | Configuration error |
| 4 | Test suite loading error |
| 5 | API call failure |
| 6 | Comparison failure (payload diff found) |
| 7 | Mock server error |
## Author
Mario Galea – [GitHub](https://github.com/mariogalea)
## License
This project is licensed under the MIT License — see the [LICENSE](./LICENSE) file for details.