Unit Tests as Documentation

• hitchstory

  28 91 8.5 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...

• CodeRabbit

  coderabbit.ai featured

  CodeRabbit: AI Code Reviews for Developers. Revolutionize your code reviews with AI. CodeRabbit offers PR summaries, code walkthroughs, 1-click suggestions, and AST-based analysis. Boost productivity and code quality across all major languages with each PR.

  

• jiter

  4 308 8.6 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...

• redis-dict

  3 53 7.6 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_...

• strictyaml

  22 1,491 1.9 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.

• doc-detective

  2 64 9.0 JavaScript

  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/

• scalasql

  1 195 8.4 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

  

• µPickle

  5 722 8.1 Scala

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

  

• SaaSHub

  www.saashub.com featured

  SaaSHub - Software Alternatives and Reviews. SaaSHub helps you find the best software and product alternatives

  

• os-lib

  5 692 8.7 Scala

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

  

• phobos

  2 1,184 9.4 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...

• testy

  1 9 3.3 JavaScript

  No fuss doctests for Node.js - test your @examples (by linus)

  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

• lmlinter

  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.

• Catch

  57 18,792 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