4

I'm creating a library, and I would like to provide a tutorial on how to use the library. Such a tutorial will contain code snippets as usage examples; therefore, I would like to test these snippets to make sure the code is correct.

How can I test examples in the documentation?

I'm thinking about some kind of interleaving documentation text with traditional unit tests, but all the ideas I've got seem to lack elegance. One option may be in adding phpdoc comments to tests and then somehow creating web/printable version of the source code. Another way may be in referencing pieces of tests from Markdown documents. Either way requires some kind of tool to put things together, and I would prefer to use an existing tool.

The library is in PHP, and it uses PHPUnit for tests, but I'm looking for inspiration regardless of the language.

(Note: I've posted this question on Stack Overflow originally, but it didn't fit well there.)

1
  • In what output format do you want the documentation? Where is problem in putting example code in public repository and have a link there from documentation? – Euphoric Nov 12 '19 at 15:16
4

I can recall 2 buzzwords:

  • Literate programming - more generic approach of blending together code (also production) and its comprehensive human-readable description. For many programming languages there are tools which can format the text as a rich text document, or extract code for compilation and execution. I can find some in php, too, though I am not sure how reliable they are. You could implement your system using this technology.

  • doctest - basically same thing as you describe, implemented long time ago as a part of python standard library. You can write snippets as part of documenting comments, and they would be executed by calling your module in a special way. Again, google knows some php implementations of this concept.

1
  • "Literate programming." Thank you. That was the term I've read about a long time ago and now I could not recall. The links provide plenty of tools to see how others dealt with this task and some of them are surprisingly simple. Thank you. – Josef Kufner Nov 11 '19 at 22:38
1

I think what you are looking for is Behavior Driven Development:

BDD is largely facilitated through the use of a simple domain-specific language (DSL) using natural language constructs (e.g., English-like sentences) that can express the behaviour and the expected outcomes. Test scripts have long been a popular application of DSLs with varying degrees of sophistication.

An example of a tool that is used in this capacity is Cucumber and the language used to write the specifications is called Gherkin.

Essentially the goal is to produce requirements that are also runnable test scripts.

1
  • BDD is very different thing. I need to include PHP source code in a book or a web page, and make sure the code is correct. (Anyway, thanks for the Gherkin link; I will use it elsewhere.) – Josef Kufner Nov 11 '19 at 22:15

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.