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

Flag	Required	Default	Description
--spec	Yes	-	Path to OpenAPI 3.0 specification file (JSON or YAML)
--endpoint	Yes	-	POST endpoint path to target (e.g., /users)
--count	Yes	-	Number of requests to generate (must be positive integer)
--base-url	No	http://localhost:8080	API server base URL
--token	No	-	Authentication token (sent as Bearer token in Authorization header)

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:

Pattern	Example Fields	Generated Value
email	email, emailAddress	Valid email address
url/uri	url, website, link	Valid URL
date	date, createdAt, timestamp	Date value
name	name, firstName, lastName, username	Realistic name
phone	phone, phoneNumber, mobile	Phone number

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.