pulse

Pulse

Pulse is a programmable reliability and load testing engine written in Go.

Lightweight, deterministic, and designed for real-world automation.

It generates controlled HTTP load against a target, collects latency and error metrics, and evaluates configurable pass/fail thresholds. Tests are driven by a YAML config file and executed through the pulse CLI.

Quick Start

From the repository root, with a Go toolchain matching go.mod:

1. Start the mock HTTP server (listens on :8080 by default):

go run ./cmd/mockserver -mode healthy

2. In another terminal, run a load test against the examples (they target http://localhost:8080):

go run ./cmd/pulse run examples/baseline.yaml

3. Print results as JSON on stdout:

go run ./cmd/pulse run examples/baseline.yaml --json

After installing the binaries:

go install ./cmd/pulse
go install ./cmd/mockserver

You can run pulse and mockserver from your PATH instead of using go run.

Use as a library in your Go project:

go get algoryn.io/pulse@latest

Expected results (with the mock server in the suggested mode from Examples):

• baseline.yaml → PASS
• mixed-errors.yaml → FAIL (thresholds)
• timeout.yaml → FAIL (thresholds)

Features

• Arrival-rate scheduling — request-driven load (requests/sec), with constant, ramp, step, and spike phases (not user/VU-based)
• Bounded concurrency — configurable goroutine limit prevents runaway resource usage
• Metrics aggregation — total, failed, RPS, latency (min, mean, p50, p95, p99, max), status code distribution, normalized error categories
• Thresholds — error_rate, mean_latency, p95_latency, p99_latency with PASS / FAIL in the text report
• HTTP transport — GET, POST, PUT, DELETE, PATCH; optional headers, body, and timeout in YAML
• CLI — pulse run <config.yaml> with human-readable text and JSON output modes
• Result hook — optional OnResult callback in Config for post-run integrations (CI systems, observability pipelines)
• Middleware pipeline — composable Middleware type with Chain and Apply helpers
• Chaos engineering — WithLatency and WithErrorRate for fault injection
• go test integration — RunT and SkipIfShort for load testing inside go test

Mock Server

Pulse includes a built-in mock HTTP server for local testing and demos (cmd/mockserver). It avoids external dependencies while you try the example YAML files.

Run (default address :8080):

go run ./cmd/mockserver -mode healthy

Optional: -addr :9090 to listen on another port (then set target.url in your YAML accordingly).

go run ./cmd/mockserver -mode mixed-errors
go run ./cmd/mockserver -mode slow

Usage

1. Write a config file

phases:
  - type: constant
    duration: 30s
    arrivalRate: 50

  - type: ramp
    duration: 30s
    from: 10
    to: 100

  - type: step
    duration: 60s
    from: 10
    to: 100
    steps: 5

  - type: spike
    duration: 60s
    from: 20
    to: 300
    spikeAt: 20s
    spikeDuration: 10s

target:
  method: GET
  url: https://api.example.com/health

maxConcurrency: 100

thresholds:
  errorRate: 0.01       # fail if error rate exceeds 1%
  maxMeanLatency: 200ms # fail if mean latency exceeds 200ms

2. Run the test

pulse run config.yaml

Optional flags:

Examples

Ready-to-run scenarios live under examples/. By default they use http://localhost:8080 — pair them with go run ./cmd/mockserver in the matching mode (see above). Expected outcomes depend on server behavior.

Exit Codes

The pulse CLI uses exit codes for automation (e.g. CI):

JSON Output

With --json, the CLI prints one indented JSON object to stdout. With --out <path>, it writes the same object to a file. Without --json, stdout still shows the text report when a result is available; with --json, stdout is JSON only, and you can still add --out to persist a copy.

Structure:

{
  "summary": {
    "total": 0,
    "failed": 0,
    "rps": 0,
    "duration_ms": 0
  },
  "latency": {
    "min_ms": 0,
    "p50_ms": 0,
    "mean_ms": 0,
    "p95_ms": 0,
    "p99_ms": 0,
    "max_ms": 0
  },
  "status_codes": { "200": 0 },
  "errors": { "http_status_error": 0 },
  "thresholds": [
    { "description": "string", "pass": true }
  ],
  "passed": true
}

• Durations — summary.duration_ms is the run length in milliseconds (integer). latency.*_ms values are also in milliseconds (floating-point).
• passed — true when every configured threshold evaluation succeeded; false if any failed. Aligns with exit code 0 vs 2 for threshold-only failures.
• thresholds — ordered list of individual checks; each entry has a human-readable description and pass.

{} and [] are valid when that part of the result is empty—for instance, no recorded status codes, no classified errors, or no threshold outcomes to list.

Example output

Text (default):

Total requests: 2250
Failed requests: 12
Duration: 1m0.41s
RPS: 37.25

Min latency: 18ms
P50 latency: 45ms
Mean latency: 52ms
P95 latency: 134ms
P99 latency: 198ms
Max latency: 312ms

Status codes:
  200: 2238
  503: 12

Errors:
  http_status_error: 12

Thresholds:
  PASS error_rate < 0.01
  PASS mean_latency < 200ms

JSON (--json):

{
  "summary": {
    "total": 2250,
    "failed": 12,
    "rps": 37.25,
    "duration_ms": 60410
  },
  "latency": {
    "min_ms": 18,
    "p50_ms": 45,
    "mean_ms": 52,
    "p95_ms": 134,
    "p99_ms": 198,
    "max_ms": 312
  },
  "status_codes": { "200": 2238, "503": 12 },
  "errors": { "http_status_error": 12 },
  "thresholds": [
    { "description": "error_rate < 0.01", "pass": true },
    { "description": "mean_latency < 200ms", "pass": true }
  ],
  "passed": true
}

Architecture

pulse run config.yaml
        │
        ▼
   config.Load()          Parses YAML → pulse.Test
        │
        ▼
    pulse.Run()           Validates inputs, evaluates thresholds
        │
        ▼
    engine.Run()          Orchestrates phases and concurrency
        │
        ▼
  scheduler.Run()         Token-bucket pacing; constant, ramp, step, and spike phases
        │
        ▼
   Scenario func          Executes the HTTP request via transport.HTTPClient
        │
        ▼
  metrics.Aggregator      Records latency, status code, and error per call
        │
        ▼
    pulse.Result          Returned to the CLI for text or JSON rendering

Components

Roadmap

v0.2.0 ✓

• Step and spike phases — discrete and burst arrival-rate scheduling
• Full HTTP method support — PUT, DELETE, PATCH
• Result hook — OnResult callback for post-run integrations

v0.3.x ✓

• Algoryn ecosystem — module path migrated to algoryn.io/pulse
• Fabric integration — ToRunEvent connects Pulse to Algoryn ecosystem
• go test integration — RunT and SkipIfShort
• Middleware pipeline — Chain, Apply, WithLatency, WithErrorRate

Upcoming

• Export formats — CSV, OpenTelemetry
• gRPC transport
• More chaos primitives — WithTimeout, WithRetry, WithJitter

Part of Algoryn Fabric

Pulse is part of the Algoryn Fabric ecosystem — an open source infrastructure toolkit for Go teams building reliable products.

License

MIT