Proposal for "Testing_DocTest"

» Metadata » Status
» Description

Testing_DocTest: A Unit Test framework for writing tests in your php code docstrings.


Testing_DocTest allows the developer to write unit tests directly in the <code></code> blocs of your PHP functions, classes and class methods.

Testing_DocTest comes with a default runner that will parse all your <code></code> blocs and will run the extracted tests, running tests is as simple as:

$ phpdt /path/to/your/code

There are several advantages in using Testing_DocTest:

  • it makes unit tests writing funnier, easier and quicker (there's no infrastructure to setup, you just install the package, write your code examples tests and you're done !);
  • it ensures that docstrings are up-to-date by verifying that all examples work as documented;
  • it enforces writing of tutorial documentation, liberally illustrated with input-output examples.

Testing_DocTest was maily inspired by the great python doctest module.


Just run:
$ pear install -f

And to uninstall:
$ pear uninstall Testing_DocTest



Todo list by priority (not exhaustive)

  • Integration with other test frameworks (phpt, PHPUnit, xUnit...);
  • Better error reports for doctest, instead of Parse error in command line code, try to report the file and line where the test fails (in the docstring);
  • Ability to manage test suites (with a "suite:" keyword for example);
  • Provide some sort of setup/teardown mechanism, but I'm not sure if it's a good idea... After all you can always include() files in doctests;
  • Provide a html runner with a bling-bling gui.

Project page at googlecode

» Dependencies » Links
  • Console_CommandLine
» Timeline » Changelog
  • First Draft: 2008-03-06
  • Proposal: 2008-03-08
  • Call for Votes: 2008-03-19
  • David Jean Louis
    [2008-03-12 10:31 UTC]

    • added "expects-file" support: expected test output can now be store in an external file;
    • added "skip-if" support: tests can now be skipped if they match a condition;
    • added "clean" support: cleaning can be done at the end of a doctest, for example to delete temporary files created by a test that failed;
    • better subprocess management in the runner;
    • ini settings can now be provided;
    • removed the "global flags" switch in the default runner: it was a bad idea;
    • some bug fixes and robustness improvements.
  • David Jean Louis
    [2008-03-14 15:04 UTC]

    • fixed pathes in tests;
    • added scripts/phpdt.bat for windows;
    • now works under windows;
    • fixed a small bug in the runner.
  • David Jean Louis
    [2008-03-18 21:00 UTC]

    • ini settings can now be set in the doctest using "// ini-set: directive=value" syntax;
    • don't read from stderr for php errors, php throws it on stdout anyway.