Hash (In)equality

In my automated testing, I often want to test a pair of hashes for equality. If the pair is equal, well enough.

But if they’re not equal, the simple way to record that is to log the failure, along with the two hashes. If the hashes are very small: I can visually compare them to determine the differences.

But for larger hashes, I can’t easily determine the differences visually. That’s where my class HashHelpler comes in.

It has method HashHelper.compare(expected, actual) that accepts the expected and actual hashes, and returns a hash having four keys and their corresponding values:

  • :ok: value is a hash containing the key/value pairs that are in both expected and actual.
  • :missing: value is a hash containing the key/value pairs that are in expected, but not in actual.
  • :unexpected: value is a hash containing the key/value pairs that are in actual, but not in expected.
  • :changed: value is a hash detailing the keys that are in both expected and actual, but whose values differ.

So: in my method Log#verdict_assert_equal?, a failed hash comparison gets and logs the detailed differences, making it easy to see what’s what.



Method Name As Documentation

Hey, Ruby coders!

Do you recognize this idiom?


Or this one?


When I wanted to do these two things in my RubyTest project, I had to Google to find out how.

Now if I put this code into my project, will I recognize these idioms later on? Next month? Next year?

I could add comments to explain, but a comment can get stale (not keep up with code changes), or get separated from its code, or even get deleted.

You can help your downstream code enhancer/maintainer by pushing an unusual idiom into a well-named method.

(Hint: If you’re not sure who is the downstream enhancer/maintainer, it’s you!)

Thus, I created this:

class ObjectHelper

  def self.get_class_for_class_name(class_name)

  def self.instantiate_class_for_class_name(class_name, *args)


PS: My GitHub project is about test automation in Ruby. It has a Tester Tour of the demo testing for a web UI and for a REST API.

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 burdettelamar@yaho.com.



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:

  • PatchLabels.call(client, 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!