About

CodeInstances keeps runs of programs as instances and replays them. It’s an open source project under the Apache License 2.0, made by SoftDevStudio.com. The code is on GitHub.

The current release is v0.6.0, the sixth one. It’s early. What it does, it does well and it’s tested, and the reference lists plainly what it can’t do yet.

Why the Project Exists

Code gets a lot of care. It sits in version control, it’s reviewed, tagged, released and kept for years. Runs get none. A program runs, talks to a few servers, prints something and exits, and the run is gone. If it failed, you have a log line and a guess.

That’s fine until the run is the thing you need. A test fails in CI and passes on the rerun. An API answered something odd once. A batch job went wrong on Tuesday and the data it read has changed since. Somebody asks what a program actually did last week, and nobody can say.

CodeInstances treats a run as something worth keeping. Your code is the blueprint, and every run of it is an instance, in the same sense that an object is an instance of a class. An instance is a file. You can replay it, hand it to a colleague, attach it to a bug report or keep it next to the code that made it. The explainer goes through the idea in plain words.

What v0.6.0 Does

  • Record any program. codeinstances record -- your command runs it behind a local proxy and keeps every HTTP and HTTPS exchange, its output, how it ended and how long it took. It works with programs in any language that respect the usual proxy settings.
  • Replay it offline. codeinstances replay run.instance runs the program again with the network replaced by the recording. It never opens a connection. It says “replay matched” or lists exactly what was different.
  • Check a fix against a recorded failure. Replay a fixed build against the same file and see whether it now behaves.
  • Compare two runs. codeinstances diff passing.instance failing.instance pairs up their calls and shows which answers changed, which calls only one run made, how each ended, what each printed and how long things took.
  • Shrink a failure. codeinstances shrink -pass passing.instance failing.instance finds the fewest of the failing run’s answers that still make the program fail, by replaying it offline with the passing run’s answers swapped in, and keeps that smallest failing instance.
  • Keep runs as regression tests. codeinstances test testdata/ replays a folder of instances: runs that passed must replay exactly, and recorded failures must now exit 0.
  • Group failures. codeinstances group failures/ fingerprints failing runs and puts the ones that fail the same way together, so repeats of one bug show as one.
  • Share runs. codeinstances serve runs a store of your own that keeps instances under their ids; push and pull move them, and report writes a bug report with the commands that bring the run back.
  • Fork a run at a step. codeinstances fork -at N answers the calls before step N from the recording and runs on from there, live, offline, or with an answer you give: a what-if.
  • Exact clock and random values in Go. The small hook package records the clock and random numbers a Go program asks for, and hands the same ones back on replay.
  • An open file format. An instance is one JSON file, described in full in FORMAT.md. Each file carries a SHA-256 id, so codeinstances verify notices any edit.

It ships as a single static binary for Linux, macOS and Windows, written in Go with nothing outside the standard library. Download it or start with the quick start.

Where It Goes Next

Keep, replay, compare, shrink, test, group, share and fork are the first eight things you can do to an instance. Others follow, one per release: signed instances as proof of what ran. That’s the direction. Each step ships when it works, and gets a plain post on this site when it does.

How the Project Works

  • Every number on this site is measured. It comes from the test results recorded in the code repository, in test/results, along with the machine they ran on.
  • Limits are written down. If something isn’t covered, the reference page says so.
  • Releases are automated. A release is built, smoke-tested on each kind of machine and published by the release workflow, with nothing published if a check fails.

Questions People Ask

Does my program need to change?

Mostly not. Any program that sends HTTP through HTTP_PROXY and HTTPS_PROXY and trusts the certificate files most clients read is captured as it is. A Go program that wants its clock and random numbers replayed too uses the hook package for them.

Which languages does it work with?

HTTP capture works for any language. In the smoke check, a plain Python program that knows nothing about CodeInstances is recorded and replayed offline. Clock and random capture is Go only in v0.6.0.

Does it keep my API keys?

By default the values of Authorization, Cookie, Set-Cookie and the common API key headers are replaced with [redacted] in the file. Only header values are redacted. A secret in a body, a URL query string or the command line stays in the file. Treat instance files like logs.

Is it a mocking library?

It overlaps with record-and-replay test tools, but it works from outside the program, for any program, and the whole run is the unit: output, exit code, every call. The file is the product, and it’s meant to outlive the test that made it.

What does it cost?

Nothing. It’s Apache 2.0.

Get in Touch

Questions, bug reports and use cases the project should look at are welcome on the contact page.