{"id":17977639,"url":"https://github.com/martinmoene/testdox","last_synced_at":"2026-04-30T06:31:09.183Z","repository":{"id":147527546,"uuid":"266728814","full_name":"martinmoene/testdox","owner":"martinmoene","description":"TestDox - generate a readable overview of test case names from the specified files.","archived":false,"fork":false,"pushed_at":"2020-05-27T09:20:40.000Z","size":164,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-02-09T12:18:07.181Z","etag":null,"topics":["documentation","python","testing-tools","unit-test"],"latest_commit_sha":null,"homepage":"https://secure.eld.leidenuniv.nl/~moene/Home/projects/testdox/","language":"Hack","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/martinmoene.png","metadata":{"files":{"readme":"Readme.md","changelog":"ChangeLog.txt","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-05-25T08:45:03.000Z","updated_at":"2020-06-13T15:45:22.000Z","dependencies_parsed_at":null,"dependency_job_id":"c9aede8f-0474-4522-9d8e-0ec4e97d4590","html_url":"https://github.com/martinmoene/testdox","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/martinmoene%2Ftestdox","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/martinmoene%2Ftestdox/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/martinmoene%2Ftestdox/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/martinmoene%2Ftestdox/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/martinmoene","download_url":"https://codeload.github.com/martinmoene/testdox/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247098961,"owners_count":20883290,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["documentation","python","testing-tools","unit-test"],"created_at":"2024-10-29T17:28:53.959Z","updated_at":"2026-04-30T06:31:04.161Z","avatar_url":"https://github.com/martinmoene.png","language":"Hack","funding_links":[],"categories":[],"sub_categories":[],"readme":"# TestDox: create simple documentation from test case names in C++\n\nSimple ideas can be powerful. TestDox is based on such an idea: *Test method names should be sentences*. Using this convention, TestDox can generate a readable overview of your [tests](http://en.wikipedia.org/wiki/Unit_test \"Unit testing at Wikipedia\"), as in:\n\n```Text\nCustomerLookup\n - finds customer by id\n - fails for duplicate customers\n```\n\nIt was Chris Stevenson\\'s idea to present the [camel case](http://en.wikipedia.org/wiki/Camel_case \"Camel case at Wikipedia\") method names in [JUnit](http://en.wikipedia.org/wiki/Junit \"JUnit at Wikipedia\") test cases as [sentences](http://en.wikipedia.org/wiki/Sentence_%28linguistics%29 \"Sentence at Wikipedia\") and in [2003](http://en.wikipedia.org/wiki/2003 \"The year 2003 at Wikipedia\") he created the [Java](http://en.wikipedia.org/wiki/Java_%28programming_language%29 \"Java at Wikipedia\") program [TestDox](http://skizz.biz/blog/2003/06/17/testdox-release-01/ \"Chris Stevenson's Blog mentioning TestDox\"). The idea has spread to tools or [unit test frameworks](http://en.wikipedia.org/wiki/Unit_test#Unit_testing_frameworks \"Unit testing frameworks at Wikipedia\") for several [programming languages](http://en.wikipedia.org/wiki/Programming_language \"Programming language at Wikipedia\") such as [C\\#](http://en.wikipedia.org/wiki/C%2B%2B \"C# at Wikipedia\") ([.net](http://en.wikipedia.org/wiki/C%2B%2B \".net at Wikipedia\")) and [PHP](http://en.wikipedia.org/wiki/C%2B%2B \"PHP at Wikipedia\") and it seems common for frameworks for [Behavior Driven Development (BDD)](http://en.wikipedia.org/wiki/Behavior_driven_development \"Behavior Driven Development (BDD) at Wikipedia\"). However I haven\\'t come across it in conventional [C++](http://en.wikipedia.org/wiki/C%2B%2B \"C++ at Wikipedia\") unit test frameworks ([check-it](http://www.google.nl/search?q=%2Btestdox+%2Bc%2B%2B \"Perform a Google search on +testdox +C++\")).\n\nThe original Java TestDox just creates an overview of the test suites and their test cases: it documents the evolving design and code in an agile way. To date unit test frameworks may be able to create the overview as part of the test run and also indicate the test\\'s success or failure as in:\n\n```Text\nCustomerLookup\n  [x] finds customer by id\n  [ ] fails for duplicate customers\n```\n\nSee for example PHPUnit, [Other Uses for Tests: Agile Documentation](http://www.phpunit.de/manual/3.5/en/other-uses-for-tests.html). Although I don\\'t know of any non-BDD C++ test frameworks that provide TestDox reporting off-the-shelf, many frameworks may support it via customization of their reporting mechanism. Below I intend to present [several examples of such customization](#framework-customization). In case you cannot create the TestDox report from your test framework, or do not want to do so, the Python TestDox script presented here may be of help.\n\n## Python TestDox script\n\nThe [Python](http://en.wikipedia.org/wiki/Python_%28programming_language%29 \"Python at Wikipedia\") TestDox script was initially created for use with the C++ test frameworks [Boost.Test](http://www.boost.org/doc/libs/release/libs/test/ \"Test at Boost\") and [CppUnit](http://en.wikipedia.org/wiki/CppUnit \"CppUnit at Wikipedia\"). It is distributed under the [Boost](http://www.boost.org/users/license.html \"about the license at Boost.org\") [open source license](http://en.wikipedia.org/wiki/Open_source_license \"Open-source license at Wikipedia\"). Feel free to grab the source code and change it to your own needs. Please [let me know](mailto:m.j.moene@eld.physics.LeidenUniv.nl?Subject=TestDox:) if you made any substantial changes or additions. We then can add those to testdox.py, so that other users also may benefit from them.\n\n## Recognized test name patterns\n\nTestDox recognizes test names that start with *test*, *testThat*, or\nwith *prefix\\_test\\[That\\]*, such as:\n\n- `testSystemExceptionIsCatchedWithCorrectReason`\n- `testThatSystemExceptionIsCatchedWithCorrectReason`\n- `format_testThatStringIsCorrectlyFormatted`\n\nIn its report, TestDox presents these names as follows:\n\n- `System exception is catched with correct reason.`\n- `format: String is correctly formatted.`\n\n## TestDox help screen\n\n```Text\nUsage: testdox.py [options] [directory | file...]\n\nCreate test documentation from testsuite files based on testdox format.  See\nalso: http://blog.dannorth.net/introducing-bdd/\n\nOptions:\n  --version        show program's version number and exit\n  -h, --help       show this help message and exit\n  -d, --debug      show debug messages\n  -v, --verbose    show more messages\n  -q, --quiet      show less messages\n  -t, --selftest   perform selftest; can also use option -v\n  --title=title    specify title for report [none]\n  --framework=fw   select test framework: Boost.Test, CppUnit [Boost.Test]\n  --format=format  select output format: html, text [text]\n  --glob=pattern   filename pattern to use with directories [*.cpp|*.h]\n  --depth=n        directory recursion depth, norecurse is 1 [recurse]\n  --norecurse      prevent visiting subdirectories [no]\n  --htmlbodyonly   only generate contents of body tag fragment [no]\n```\n\n## TestDox output examples\n\n- [CppUnit example](website/output/cppunit/)\n- [Boost.Test example](website/output/boosttest/)\n\n## Framework customization\n\n### Boost.Test\n\n- [View customization](website/boosttest/)\n- [Boost.Test at Boost](http://www.boost.org/doc/libs/release/libs/test/)\n\n### UnitTest++\n\n- [View customization](website/unittestpp/)\n- [UnitTest++ on Google Code](http://code.google.com/p/unittestpp/), svn [repository](http://unittestpp.googlecode.com/svn/)\n- [UnitTest++ on SourceForge](http://unittest-cpp.sourceforge.net/)\n\n## Downloads\n\n- [testdox.py](testdox.py) ([view highlighted](website/src/))\n- [Readme.txt](Readme.txt)\n- [ChangeLog](ChangeLog.txt)\n- [ToDo](ToDo.txt)\n- [TestDox-0.1.4-alpha.zip](https://secure.eld.leidenuniv.nl/~moene/Home/projects/testdox/src/TestDox-0.1.4-alpha.zip)\n- [testdox.exe](https://secure.eld.leidenuniv.nl/~moene/Home/projects/testdox/src/testdox.exe) packed executable\n\n## Resources\n\n- [TestDox](http://en.wikipedia.org/wiki/TestDox) at Wikipedia\n- [Behavior Driven Development (BDD)](http://en.wikipedia.org/wiki/Behavior_driven_development) at Wikipedia\n- [Introducing BDD](http://blog.dannorth.net/introducing-bdd/), by Dan North\n- [Agiledox](http://joe.truemesh.com/blog//000047.html), by Joe Walnes\n- [AgileDox project (Java)](http://agiledox.sourceforge.net/), by [Chris Stevenson](http://skizz.biz/blog/)\n- AgileDox project [CVS repository](http://agiledox.cvs.sourceforge.net/viewvc/agiledox/) with testdox, nAgileDox\n- [TestDox release 0.1](http://skizz.biz/blog/2003/06/17/testdox-release-01/) blog post by [Chris Stevenson](http://skizz.biz/blog/)\n- [TestDox for IntelliJ IDEA](http://testdox.codehaus.org/), Codehaus\n- [TestDox for .NET](http://www.testdox.com/) , by NN\n- [TestDox (PHPUnit)](http://www.phpunit.de/manual/3.5/en/other-uses-for-tests.html), by [Sebastian Bergmann](http://sebastian-bergmann.de/)\n- [PHPUnit Best Practices](http://www.slideshare.net/sebastian_bergmann/phpunit-best-practices), by [Sebastian Bergmann](http://sebastian-bergmann.de/)\n- [Protest](http://xspecs.sourceforge.net/protest.html) test framework for Python, by [Nat Pryce](http://www.natpryce.com/) (Subversion [trunk](https://xspecs.svn.sourceforge.net/svnroot/xspecs/protest-python/trunk \"Subversion trunk at SourceForge\"))\n- [Programming with GUTs](http://www.stickyminds.com/pop_print.asp?ObjectId=13833\u0026ObjectType=ART) and [GUT Instinct](http://www.stickyminds.com/pop_print.asp?ObjectId=14973\u0026ObjectType=ART), by [Kevlin Henney](http://www.curbralan.com/)\n- [Naming standards for unit tests](http://weblogs.asp.net/rosherove/archive/2005/04/03/TestNamingStandards.aspx), by Roy Osherove\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmartinmoene%2Ftestdox","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmartinmoene%2Ftestdox","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmartinmoene%2Ftestdox/lists"}