Gommander

Gommander is a CLI tool built in Go for declarative HTTP API testing and automation. It allows you to run acceptance and stress tests defined in JSON configuration files.

Features

• Declarative test plans: Define complex test scenarios with variables, assertions, and variable extraction.
• Fail-fast validation: Validates test plans before execution, providing contextual error messages.
• Detailed reporting: Table and JSON output formats.
• Typed exit codes: Easy integration into CI/CD pipelines.

Installation

go install github.com/jarlex/gommander@latest

Or clone the repository and build:

git clone https://github.com/jarlex/gommander.git
cd gommander
make build

Usage

Run tests using the CLI:

gommander --config ./plan-directory

Options

• --config: Path to the test plan configuration directory or file.
• --dry-run: Load and validate plan, print summary, and exit without executing.
• --format: Output format: table (default) or json.
• --verbose, -v: Show detailed request output.
• --quiet, -q: Show only summary output.
• --timeout: Override plan timeout (e.g., '30s', '1m').

Exit Codes

• 0: Success (all tests passed)
• 1: Validation/Configuration Error (invalid plan or arguments)
• 2: Test Failure (one or more tests failed)

Plan Format

A test plan consists of Steps, which contain Tasks, which execute Requests.

Plan (plan.json)

{
  "name": "API Test Plan",
  "timeout": "30s",
  "variables": {
    "base_url": "https://api.example.com"
  },
  "steps": [
    {
      "name": "Authentication",
      "concurrentUsers": 1,
      "tasks": [
        {
          "name": "Login",
          "request": {
            "url": "[[base_url]]/login",
            "method": "POST",
            "paramsBody": "{\"username\": \"test\", \"password\": \"password\"}",
            "headers": {
              "Content-Type": "application/json"
            }
          },
          "asserts": [
            {
              "source": "status",
              "operator": "equal",
              "value": "200"
            }
          ]
        }
      ]
    }
  ]
}

Plan Structure

• Plan: Top level object. Can contain variables and a list of Steps.
• Step: Represents a logical grouping. Supports concurrentUsers for basic load testing.
• Task: A single action. Contains a Request, Asserts (for validation), and Extracts (for capturing variables from responses).
• Request: The actual HTTP call configuration.

Assertions

Assertions validate the HTTP response.

• source: What to check (status, body, header.[name])
• operator: How to compare (equal, contains, not_equal)
• value: Expected value.

Variables

Variables are defined at the plan level or extracted during tasks. Use them in requests with [[variable_name]].