Goals of This Project

The goals of the project, from its author.

The initial prompt that kicked the project off. It starts by asking the Agent what kind of test framework would help it write better code.

Throughout this diary, "Agent" is Claude Fable 5.2, "user" is isaacs

We are going to build a new test framework, with a focus on human and coding agent ergonomics, flexibility across runtimes, highly optimized rapid feedback loops, "batteries included" features, out of the box reliable TypeScript support, reliability, reproducibility, and simplified use cases, so that high-quality code is the easiest thing to make by default.

Some quick initial thoughts:

It needs to be VERY fast. If it can't out-perform the best in class test frameworks today (vite, jest, tap, even the native deno test and bun test frameworks) then we're not done.
Test programs should be runnable with a minimum of harness support. No magic globals, no special flags.
Test results should be inspectable, to the point of being able to replay a test run, investigate what's going on when things get wedged, and even ask questions after the fact about what went wrong.
The interface for writing test programs should be terse enough to be efficient to write, while still extremely clear while reading. Everything must be strictly typed so that editors, LSPs, LLMs, and so on, can easily reason about what's going on.
Coverage is not optional, and should be leveraged for deep insights into the codebase. The system should make it easy to see which parts of the program are uncovered, and which are sufficient.
It should feel natural to anyone who's familiar with modern test frameworks in JavaScript, but provide a surprising amount of value out of the box, with a minimum of effort.
I'd like to take advantage of the latest in modern JavaScript runtime technologies. We can use diagnostics_channel listeners to pass information, store data in sqlite databases, you name it. Whatever is useful, nothing is off the table.

About this folder#

As we build this project, this will be your place to record decisions, make plans, and track how things work, both for ongoing maintenance and development, as well as to provide to future coding agents who use the tool. However, let's not flood the context windows either; ensure that items in here are discoverable, with terse helpful index files, so that an agent can find what it's looking for easily, based on the task at hand.

In short, organize it however you like; make it your own.

Initial Brainstorm#

Before we get started on implementation details, I want to make sure that we're building something that coding agents will find useful and productive. What do YOU find to be lacking in the current selection of testing tools in JavaScript? What would help an agent like yourself write better code, more reliably?

Take your time and try to answer this question thoroughly, in docs/01-agent-ideation.md.