Code is versioned, reviewed and kept for years. Its runs are thrown away. When a run fails, it leaves a log line and a guess. A CI test fails at 3 a.m. and the run is stuck on one machine. An API answered oddly once and never again. A maintainer gets an issue saying “sync breaks against our account” and has no way into the reporter’s account.
CodeInstances keeps the run. It treats each run as an instance of the code, the way an object is an instance of a class, and saves it as one file. That file can be replayed later with no live servers, compared with another run, shrunk to the answers that cause a failure, attached to a bug report and kept with the code.
The Pitch in Four Numbers
- 10 of 10 offline replays matched the recording, with the live servers stopped.
- 23 calls, HTTPS and HTTP, recorded in 71 milliseconds and kept in one 20,631-byte file.
- 37 to 49 milliseconds per replay, none of which opened a connection.
- 118 Go tests passing, with nothing found by the race detector.
How It Works
record runs a program behind a local proxy that talks to the real servers and saves every HTTP and HTTPS exchange, plus the program’s output, exit status and duration. replay runs the same program against the proxy, which answers from the file. No live servers, no network. The replay either matches the recording or produces a list of what changed. Programs that honour the usual proxy settings and trust the certificate files most clients read are captured without any changes.
From there the verbs pile up. diff compares two runs and shows where the failing one went wrong. shrink works out which answers in a failing run actually cause the failure and keeps the result as a test. test replays a folder of instances as regression tests. group sorts failing runs by fingerprint and tells you how many different ways the program fails. fork replays a run up to a chosen step and then lets it carry on live or with a what-if answer.
Runs can be shared through a self-hosted store with push and pull by ID, which makes bug reports reproduce. Each instance’s ID is the SHA-256 of its contents, so verify catches any edit, and signing adds a check of who kept a run. A store can accept only signed runs and, with serve -run, replay or fork them for anyone holding its token. It’s one static Go binary for Linux, macOS and Windows.
Privacy
By default, Authorization, Cookie and Set-Cookie headers and common API key headers are replaced with “[redacted].” Secrets in request bodies, URL query strings or the command line aren’t, so the site’s advice is to treat instance files like logs.
Who It’s For
- Developers fighting flaky CI tests that fail once and pass on rerun.
- Open-source maintainers who need a bug report they can actually reproduce.
- Teams depending on outside APIs that sometimes answer strangely.
- QA engineers building regression tests from real runs instead of hand-made mocks.
Limits
The project calls itself early, and the reference lists what isn’t supported yet. Recording the clock and random numbers works only for Go programs. It isn’t a mocking library: it works from outside the program, in any language, and treats the whole run as the unit.
The Four-Question Screening
Every project featured here gets the same four questions, the way you’d screen a startup idea.
1. Where is the money in it?
CodeInstances is free under Apache 2.0, with no paid tier. The store is the natural business. Teams want a shared place to keep, search and replay runs, with access control, retention and signing, and they’ll pay for it hosted. Debugging tools and flaky-test analytics are established markets, and “attach a replayable run to every failure” is a clear upgrade on logs. Enterprise features like secret scanning in bodies and SSO for the store are obvious paid extras.
2. What real problem does it solve?
Failures that can’t be reproduced. Without the original run, debugging is guesswork: the server answered differently, the data changed, the machine is gone. Keeping the run turns “can’t reproduce” into “replay it.”
3. The technology in plain words
Think of a flight recorder for a program. It notes every conversation the program had with the outside world while it ran. Later, you can play the flight back on the ground, exactly as it happened, compare it with a good flight, or stop it halfway and ask “what if the tower had said something else?”
4. Moat and differentiation
Record-and-replay test tools exist, usually tied to one language or test framework. CodeInstances works from outside any program and makes the run file the product: signed, shareable, shrinkable and meant to outlast the test that created it. The moat that can grow is the file format and the store, since once teams keep their runs somewhere, those runs become an asset they won’t want to move.
Why It Matters
A run you can replay is worth more than a thousand log lines. Making runs as durable as code changes how teams debug, test and report bugs.
Follow the Project
Read what a code instance is and why runs should be kept like code, start with the quick start, get it from the download page, or see the code in the CodeInstances repository on GitHub. CodeInstances is listed with the other open-source projects on SoftDevStudio.com, and more featured projects are in the Projects section.