Category Archives: Uncategorized

Updated Ruby Gem markdown_helper

I’ve put up a new version of gem markdown_helper.

Now, by default, the output markdown has added comments that show:

* The path to the template file.
* The path to each included file.
* The image description (original) for each resolved image file path.

You can suppress those comments using the pristine option.


My GitHub Markdown Tips


I posted earlier about Richard Kim’s blog post that has some great tips for building an effective page on GitHub.

A few of my own:

    • It’s not just
      • You can have any number of markdown pages.
      • They can be in any directories.
      • They can have filenames other than
      • The only ‘requirement’ is that for GH to render a markdown page properly, it must have the .md file extension.
    • You can link to a page with a normal GitHub URL:
      • This lands readers at the top of the page, where they see various project information. (The actual markdown text will be farther down the page.)
    • You can link to a title in the markdown on a page with an extended URL:
      • This lands the browser (Firefox at least) exactly at the title, not at the top of the page. (Get the exact URL from title’s link icon.)
      • The target title can be any title on the page (not just the main one, identified with a single #.)
    • This is especially useful for linking among markdown pages, so that the reader lands in the markdown text, instead of at the top of the page.
    • I’ve done this with my project’s Tester Tour, where each page in the tour has navigation links, forward and backward.
    • I have a MarkdownHelper class that I use to:
      • Build the tour by adding the navigation links.
      • Include external files by inlining them.
      • Add text highlighting if the file is .rb or .xml. (This can be extended to any language known to GitHub).
      • Query: Should this class be made into a Ruby gem?


    • Linking from markdown to an HTML file:
      • If you link in the usual way, the HTML will not be rendered:
      • If you link in a special way, the HTML will be rendered:
      • I would illustrate, but from here opening either type of link causes the HTML to be rendered. The difference is seen only in GitHub markdown.
      • But you can see it work via the link at the foot of

Reviewers Needed

I am pretty well finished with the Tester Tour of the example testing for the GitHub API.  It shows, from the tester’s point of view, how the REST API testing framework works.  This is part of my own GitHub project, RubyTest.

I’ll be grateful for any reviewers’ comments, which can be created as Issues on the RubyTest project itself (best, b/c records!), or can be emailed directly to me at



Keeping the Documentation Green

Everyone loves a good example in the documentation.  Often, in the software world, the example is code.

Fair enough.

But does that example code actually work?  If it did work at some point in the past, does it still work?

The only way to know for sure is to run it!

Over at my GitHub project, RubyTest, I’m building a tester ‘tour’ of part of the project.  Each ‘stop’ in the tour consists of a small test (code) and its output (a log).

Each time I do a build of the tour, the build procedure executes each test and captures its refreshed log.  These are both plugged into a text file that becomes the markdown page for a tour stop.

So I always know that the test code still works!

Check it out:

Behold, the Endpoint Object

In testing web applications, the page object design pattern has become justifiably famous. Its job is classic data hiding: each such object encapsulates an HTML page.

When I began working on my first framework for testing a REST API, I asked myself how, if at all, this encapsulation principle applies there. And the immediately obvious answer is: the endpoint object.

Just as the page object encapsulates an HTML page, so does the endpoint object encapsulate a REST API endpoint. Each endpoint has its own encapsulating class.

Now an endpoint does not have a name, exactly, but it does have an HTTP method and a URL. I’ve used those to construct the endpoint class name.

Examples (from my framework for testing for GitHub’s own REST API):

Method and URL Endpoint Class Name Effect
GET /labels GetLabels Get all labels.
POST /labels PostLabels Create a label.
GET /labels/:name GetLabelsName Get the named label.
PATCH /labels/:name PatchLabelsName Update the named label.
DELETE /labels/:name DeleteLabelsName Delete the named label.

A test framework should make things simple for the tester, right? To that end, the methods in these objects accept and return actual Ruby Label objects, not raw JSON. The methods transparently handle the transforms between JSON and those objects.

Each endpoint has four such methods. Using PatchLabels as an example:

  •, label) creates a label and returns the created label as a Label object.
  • PatchLabels.call_and_return_payload(client, label) does the same, but returns both the Label object and the raw JSON payload (in case the caller want to examine it).
  • PatchLabels.verdict_call_and_verify_success(client, log, label) creates a label and returns the created label as a Label object, also logging relevant verdicts.
  • PatchLabels.verdict_aberrant(client, log) accesses the endpoint with various error-causing aberrations, logging relevant verdicts, and returning nothing.

Voilà, the endpoint object!