A spec-driven test data generator in Common Lisp. No hardcoded structs. No maintenance.
Point it at an OpenAPI spec, tell it what schema you want, and it generates structurally valid JSON test data. When the API changes, handroll changes with it.
# List available schemas
handroll api.json --list
# Generate a single instance
handroll api.json Order
# Generate multiple instances
handroll api.json Order -n 5
# Works with URLs too
handroll https://petstore3.swagger.io/api/v3/openapi.json Pet -n 3
# Pin specific fields (dot notation for nested)
handroll api.json Order -s status=pending
handroll api.json Pet -s name=Grendel -s category.name=familiar
# Compact output (no indentation)
handroll api.json Order -c
# Control recursion depth and array length
handroll api.json Order -d 5 -a 2- Loads an OpenAPI 3.x (or Swagger 2.x) spec
- Resolves
$ref,allOf,oneOf,anyOfcompositions - Walks the schema tree and generates data based on types, formats, enums, and constraints
- Outputs valid JSON
When schemas specify formats, handroll generates appropriate data:
| Format | Example Output |
|---|---|
uuid | a3f7b2c1-4d8e-4f9a-b2c1-d8e4f9a3f7b2 |
date | 2024-03-15 |
date-time | 2024-03-15T14:30:00Z |
email | delta.foxtrot@example.com |
uri | https://example.com/bravo/4521 |
ipv4 | 192.168.42.7 |
hostname | alpha.example.com |
Enums are respected — if a field has "enum": ["placed", "approved", "delivered"], handroll picks from those values.
Requires Roswell:
brew install roswell # macOS
ros setup
ros install yason dexador cl-ppcre alexandria
# Then either run directly:
ros handroll.ros <spec> <schema>
# Or install as a command:
ros install handroll.ros
handroll <spec> <schema>beer-me — template query management for debugging. handroll generates the mess, beer-me helps you investigate it.
GPL-3.0