runn
runn is a Go-based tool and library for running multi-step scenarios (runbooks) defined in YAML, supporting HTTP, gRPC, database queries, Chrome DevTools Protocol, and SSH/local commands. It serves dual roles: as a CLI for scenario-based testing and automation, and as a Go test helper package for integration testing.
Key facts
Objective fields from the source. Values we can't verify are shown as “Unknown” rather than guessed.
| Field | Value |
|---|---|
| Repository | k1LoW/runn |
| Owner | k1LoW |
| Primary language | Go |
| License | MIT — OSI-approved |
| Stars | 639 |
| Forks | 54 |
| Open issues | 26 |
| Latest release | v1.9.4 (2026-06-30) |
| Last updated | 2026-07-06 |
| Source | https://github.com/k1LoW/runn |
What runn is
runn executes ordered or map-based runbook steps with state propagation, templating via Go's text/template syntax, and pluggable runners (HTTP, gRPC, DB, CDP, SSH). Built in Go with a single-binary distribution model, it integrates with httptest.Server, sql.DB, and grpc.Server for Go testing workflows.
Get the runn source
Clone the repository and explore it locally.
git clone https://github.com/k1LoW/runn.gitcd runn# follow the project's README for install & configurationNeed it deployed, integrated, or customized instead? DEV.co ships production installs.
Best use cases
Implementation considerations
- Runbooks require YAML proficiency; complex scenarios may become difficult to maintain without strong templating discipline and variable management.
- State is passed between steps via indexed arrays (steps[0].res) or named maps; naming conventions should be enforced to avoid fragility.
- Runner configuration (HTTP URLs, DB DSNs, gRPC endpoints) must be environment-aware; use environment variable substitution or external config for multi-environment CI/CD.
- Error handling is binary (step passes or fails); fine-grained assertion logic requires embedded test expressions in YAML, which can become opaque.
- Debugging runbooks requires CLI logging flags or Go test output; add verbose mode to runbooks early in development to reduce troubleshooting friction.
When to avoid it — and what to weigh
- Non-Go Codebases — While CLI usage is language-agnostic, the library mode is Go-specific. No native SDKs for Python, Node.js, or Java documented.
- Visual / Complex UI Testing — Chrome DevTools Protocol support is basic; Selenium/Playwright are better suited for interactive browser testing at scale.
- High-Throughput Load Testing — runn is designed for scenario validation, not sustained load generation. Use dedicated tools (k6, JMeter) for performance benchmarking.
- Closed-Source / Proprietary Compliance Requirements — MIT license is permissive but requires review by legal teams in regulated industries; no commercial SLA or indemnification offered.
License & commercial use
runn is licensed under the MIT License, a permissive OSI-approved license. Permits commercial use, modification, and distribution with minimal restrictions (attribution required, no warranty). No copyleft obligations.
MIT license permits commercial use without licensing fees or vendor approval. However, no warranty, SLA, or indemnification is provided. Organizations using runn in production should conduct their own testing and have contingency plans for maintenance gaps. Consider contributing back or funding development if business-critical.
DEV.co evaluation signals
Editorial assessment — not user reviews. Directional, with an explicit confidence level.
| Signal | Assessment |
|---|---|
| Maintenance | Active |
| Documentation | Adequate |
| License clarity | Clear |
| Deployment complexity | Low |
| DEV.co fit | Good |
| Assessment confidence | High |
Runbooks may embed credentials (passwords, tokens, API keys) in YAML files; use environment variable substitution (${VAR_NAME}) to avoid secrets in version control. No built-in secret rotation, audit logging, or encryption at rest. SSH and Chrome DevTools Protocol runners require careful authentication setup. Validate input data in runbook assertions to prevent injection attacks if runbooks are user-generated.
Alternatives to consider
Postman / Postman CLI
Mature API testing with UI/CLI modes, extensive integrations, and enterprise support. Heavier footprint and vendor lock-in; no multi-protocol support (gRPC, SSH) in free tier.
k6 / Grafana k6
Modern load testing and scenario scripting in JavaScript; superior performance metrics and cloud integration. Focuses on load/stress testing, not functional integration testing.
Cucumber / Gherkin
BDD-style scenario testing with human-readable syntax. Language-agnostic and widely adopted. Steeper learning curve; less suitable for API-first testing without custom step definitions.
Build on runn with DEV.co software developers
Explore runn's YAML-driven runbook model for API testing, database validation, and workflow automation. Start with the quickstart guide or integrate into your Go test suite.
Talk to DEV.coRelated on DEV.co
Explore the category and the services that help you build with it.
runn FAQ
Can I use runn without writing Go code?
Does runn support database transactions and rollback?
How do I manage secrets in runbooks?
Is runn suitable for production monitoring?
Custom software development services
Adopting runn is usually one piece of a larger software development effort. As a software development agency, DEV.co provides software development services and web development expertise — pairing senior software developers and web developers with your team to design, build, and operate open-source testing software in production.
Ready to streamline your integration testing?
Explore runn's YAML-driven runbook model for API testing, database validation, and workflow automation. Start with the quickstart guide or integrate into your Go test suite.