Writing your test assertions in your function comments (just before the code)?

Question

I'm using PHP and PHPUnit. Something bothers me: the fact that the assertions are in another class (too easy to forget or to ignore, for any new programmer in the project).

If the test assertions can be written just above the code, it will be easier to maintain, or difficult to ignore, I guess.

How useful can it be?

/**
 * @assertions for mycode goes here
 */
 public function mycode() {}

Answer 1

Doctest is what I was looking for. Thanks to mattnz.

Original Python Doctest module

A post on docstring-driven testing

And implementations in others languages...

PHP Doctest

Elixir Doctest

Haskell Doctest

elm-doctest

Rust Doctest

Answer 2

Gypsy included specifications and assertions in the language itself. Part of the Gypsy programming system and methodology was generation of verification conditions (theorems to be proved) that proved the correctness of the code.

The Gypsy program demonstrated, among other things, that, contrary to popular belief, it IS possible to deliver entirely bug-free code. The Message Flow Modulator was a small program, that sat on a serial line and filtered messages passing through. The MFM was developed at UT Austin. The acceptance test suite was developed independently, by a team on the West Coast. The MFM saw the acceptance test suite for the first time at the customer acceptance test at PAX River, and it passed, on the first try, no deviations, no waivers, no yeabuts, no NOTHING. It PASSED. (Don Good, the principal investigator on the project, told me that it was a long time before his phone stopped ringing after that news got out.)

Answer 3

The Java Modeling Language (JML) might be close to what you mean. It provides a formalized way to express the contract of a function or class in special comments and there exist tools to convert these into run-time assertions or unit tests but by default these will just be comments and have zero overhead.

The following example is taken from the Arc class in the digraph example on the JML website. The comment with the @s defines the contract.

/** Invert the direction of this arc. */
/*@ public normal_behavior
  @   assignable source, target;
  @   ensures source == \old(target) && target == \old(source);
  @*/
public void flip() {
    NodeType temp = source;
    source = target;
    target = temp;
}