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() {}

• Doc Brown: It am not sure if this is what you are looking for, but I guess it could be "design by contract". For PHP, this former SO post might be useful.. Note that this does not mean to put "all test assertions right above the function they testing" (which could easily lead to a big mess). And let me say I think it overhasty to misinterpret your question as a typical "tool recommendation".
• CodesInChaos: Cobra has a similar feature, but it doesn't use comments for it.
• Doc Brown: @Ixrec: would you mind to enlighten me why you still voted for closing as "tool recommendation" after I edited the question to make clear that is not the focus here?
• mattnz: Have a look at Python's Doctest.
• Loren Pechtel: @gnat I don't see that this is a question of what's the best software, but rather a question of whether anything of the sort exists. It's a feature I have long wanted, put the code and it's tests together.

Answer 1

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.)

• Brandin: Passing all tests is absolutely not a demonstration of "bug-freeness". Don't get me wrong, it's not bad to pass all tests. But passing all tests is the bare minimum you want before pushing the software out - it takes much more effort to be "bug-free" (if that's even possible).
• Loren Pechtel: I did that once in school. We were in teams, I finished the real code, my partner's test code wasn't ready. I ran my code against the test engine that would be used to turn it in to see what would happen (I was intending to use it as a rather uninformative debugger)--it passed. Zero bugs isn't proof the method is bug free!

Answer 2

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;
}

Answer 3

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