Unit Tests as Documentation

1. hitchstory

   1 28 104 5.1 Python

   Type-safe YAML integration tests. Tests that write your docs. Tests that rewrite themselves.

   

   Executable documentation:

   Hitchstory is a type-safe StrictYAML python integration testing framework exploring some interesting ideas around this.

   https://hitchdev.com/hitchstory/

   Example:

   https://hitchdev.com/hitchstory/using/behavior/run-single-na...

   Source:

   https://github.com/hitchdev/hitchstory/blob/master/hitch/sto...

2. AppSignal

   www.appsignal.com sponsored

   Monitoring that respects your time & budget. APM, error tracking, and dashboards for modern web apps. Ten-minute setup, transparent flat pricing, and support from engineers who actually use the product.

   

3. jiter

   2 5 546 8.0 Rust

   Fast iterable JSON parser.

   

   A trick I use a lot these days is to take the unit tests from an under-documented library, dump them into an LLM and ask it to write me detailed usage documentation.

   This works REALLY well. I've even occasionally done some of my own reviewing and editing in those docs and submitted them back to the project. Here's an example: https://github.com/pydantic/jiter/pull/143 - Claude transcript here: https://gist.github.com/simonw/264d487db1a18f8585c2ca0c68e50...

4. redis-dict

   3 3 76 1.4 Python

   Python dictionary with Redis as backend, built for large datasets. Simplifies Redis operations for large-scale and distributed systems. Supports various data types, namespacing, pipelining, and expiration.

   

   Have used unit tests as documentation for while, big fan. A example of recent new feature to a project.

   https://github.com/Attumm/redis-dict/blob/main/extend_types_...

5. strictyaml

   4 26 1,622 0.0 Python

   Type-safe YAML parser and validator.

   

   I dont think it is about discipline. At its core, a good test will take an example and do something with it to demonstrate an outcome.

   That's exactly what how to docs do - probably with the same examples.

   Logically, they should be the same thing.

   For example:

   https://github.com/crdoconnor/strictyaml/blob/master/hitch/s...

   And:

   https://hitchdev.com/strictyaml/using/alpha/scalar/email-and...

   You just need a (non turing complete) language that is dual use - it generates docs and runs tests.

6. doc-detective

   5 6 131 9.8 TypeScript

   Doc Detective is an open-source documentation testing framework that makes it easy to keep your docs accurate and up-to-date.

   

   Not that this solves the hard problem, but there's a simonw post for that: https://simonwillison.net/2018/Jul/28/documentation-unit-tes...

   Including screenshots, which a lot of tech writing teams raise as a maintenance burden: https://simonwillison.net/2022/Oct/14/automating-screenshots...

   Then there are tools like Doc Detective to inline tests in the docs, making them dependent on each other; if documented steps stop working, the test derived from them fails: https://doc-detective.com/

7. scalasql

   6 2 260 7.2 Scala

   Scala ORM to query SQL databases from Scala via concise, type-safe, and familiar case classes and collection operations. Connects to Postgres, MySql, H2, and Sqlite out of the box

   

8. µPickle

   7 5 766 7.6 Scala

   uPickle: a simple, fast, dependency-free JSON & Binary (MessagePack) serialization library for Scala

   

9. Kargo

   akuity.io sponsored

   Stop Scripting Promotions. Start Shipping with Kargo. Kargo automates promotion across dev, staging, and prod with approval gates and verification. Open source, built by the team behind Argo CD. Download now.

   

10. os-lib

    8 5 742 6.7 Scala

    OS-Lib is a simple, flexible, high-performance Scala interface to common OS filesystem and subprocess APIs

    

11. phobos

    9 2 1,258 9.1 D

    The standard library of the D programming language

    

    > Good documentation is good as far as it aids understanding. This might be a side effect of tests, but I don't think it's their goal. A good test will catch breaks in behaviour, I'd never trade completeness for readability in tests, in docs it's the reverse.

    The D language standard library use the two. When you generate the documentation from the comments attached to a declaration, the following unittests (they are identified using a special markup, (that is just triple slashes...) are also included.

    Example once rendered [0], in the source you see the examples are actually unit tests [1].

    [0]: https://dlang.org/phobos/std_algorithm_searching.html#.all

    [1]: https://github.com/dlang/phobos/blob/master/std/algorithm/se...

12. testy

    10 2 86 4.2 JavaScript

    No fuss doctests for Node.js - test your @examples

    

    As a fan of literate programming, I hope this could be a tool in the box for Node.js developers: Testy is basically doctests for Node.js, building off JSDoc's @examples stanza.

    I would be honored by anyone checking it out: https://github.com/linus/testy

13. lmlinter

    11 1 0 3.4 Go

    Golang test linter based on language models

    

    Here is a really bad POC for golang tests, if anyone is interested: https://github.com/nzachow/lmlinter

    Right now it just prints the prompt in the terminal.

14. Catch

    12 62 21,465 8.9 C++

    A modern, C++-native, test framework for unit-tests, TDD and BDD - using C++14, C++17 and later (C++11 support is in v2.x branch, and C++03 on the Catch1.x branch)

    

    This is one area where a BDD style framework like catch2[0] really shines, IMO. The way tests are written in this style naturally lends itself to self-documenting each branch

    [0]: https://github.com/catchorg/Catch2

Suggest a related project