seedshot

SeedShot

A CLI tool that generates and fires bulk HTTP POST requests to populate development databases with realistic test data. Parses OpenAPI 3.0 specifications, generates fake data matching schema definitions, and sends sequential requests to specified endpoints.

Installation

go install github.com/qolby/seedshot@latest

Quick Start

seedshot --spec api.yaml --endpoint /users --count 10

Usage

seedshot --spec <path> --endpoint <path> --count <n> [--base-url <url>] [--token <token>]

Flags

Examples

Basic usage:

seedshot --spec api.yaml --endpoint /users --count 10

With authentication and custom base URL:

seedshot --spec api.yaml --endpoint /users --count 100 --base-url https://api.example.com --token abc123

How It Works

1. Parses your OpenAPI 3.0 specification file (JSON or YAML)
2. Extracts the request body schema for the specified POST endpoint
3. Generates fake data matching each field's type and format
4. Sends requests sequentially and displays progress
5. Reports success/failure summary with elapsed time

Supported Schema Types

• string - generates realistic text values
• number - generates floating-point numbers
• integer - generates integer values
• boolean - generates true/false
• array - generates arrays with appropriate element types
• object - generates nested objects with appropriate field types

Field Name Pattern Recognition

SeedShot recognizes common field name patterns (case-insensitive) and generates appropriate fake values:

Required vs Optional Fields

• Fields marked as required in the schema are always included
• Optional fields are randomly included with 50% probability

OpenAPI Spec Requirements

Your spec must be OpenAPI 3.0 format with POST endpoints that define request body schemas:

openapi: 3.0.0
info:
  title: Example API
  version: 1.0.0
paths:
  /users:
    post:
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - name
                - email
              properties:
                name:
                  type: string
                email:
                  type: string
                age:
                  type: integer

See examples/simple.yaml for a more complete example.

Output

Parsing OpenAPI spec...
Found endpoint: POST /users
Generating 10 requests...
Sending requests to http://localhost:8080/users...
1/10 - Request successful
2/10 - Request successful
3/10 - HTTP 400: {"error":"validation failed"}
...
10/10 - Request successful

Completed: 9 successful, 1 failed in 2.3s

Error Handling

SeedShot provides helpful error messages for common issues:

Error: spec file not found: openapi.yaml
  → Check that the file path is correct

Error: endpoint /api/users not found in specification
  → Available POST endpoints: /api/posts, /api/comments

Error: endpoint /api/users is not a POST endpoint
  → Only POST endpoints are supported in this version

Error: count must be a positive integer, got: 0
  → Valid count values: 1, 2, 3, ...

If some requests fail (network errors or non-2xx status codes), execution continues with remaining requests and a summary is displayed at the end.

Dependencies

• kin-openapi - OpenAPI 3.0 spec parsing
• gofakeit - Realistic fake data generation
• cobra - CLI framework

License

MIT License - see LICENSE for details.