Testing and Documenting a Rubygem
In this post we're going to continue working on the gem we made in the previous tutorial, getting it ready for publication by adding tests with RSpec and documenting it using YARD.
Setting up RSpec
Before you make any gem public it's good practice to add a suite of tests – especially if you expect other people to be working on it and contributing back to your codebase.
There are a few different testing tools available for Ruby, but in this tutorial we're going to be using RSpec. If you're following along, install the gem with the following command:
As well as installing the RSpec gem on your local machine, we need to add it as a dependancy in our
listless.gemspec file. Anyone who forks our gem should be running tests in a development environment (rather than production), so it makes sense to use the
gem.add_development_dependency method here.
A common convention when using RSpec is to keep all your tests scripts contained in a directory named
spec. We should also make sure that all the names of our test scripts end in
_spec.rb, so that the RSpec executable knows that they contain tests that need to be run. Let's create the directory and a single file for holding our tests.
Great stuff. We'll now open the empty
listless_spec.rb file and add a couple of simple behavioral tests – one that checks the gem is transforming an Array into an HTML list, and another which checks that characters are being HTML encoded properly.
It's also worth pointing out the
require_relative statement at the top of the code, which gives the tests access the main
Listless module and allows them to run correctly.
We can execute our tests by running
rspec from the terminal, passing in the name of the folder holding our test scripts.
If the results look good and you get a pair of dots indicating that the two tests have passed, then now is a good time to commit the changes.
Complete the README
When we used Bundler to set up our gem in the previous tutorial, a boilerplate
README.md was created. Arguably the most important piece of documentation for a gem, the content of the README acts as the homepage when we generate YARD documentation (in the next section), and is also used by GitHub and Bitbucket as the default landing page for a repository.
Let's complete this by filling in the description and usage sections, using Markdown for formatting.
Again, let's commit the changes.
Finally we're going to add some documentation using YARD. Unlike RDoc (another common documentation tool) YARD ships as a standalone gem which we'll first need to install.
Documenting the gem is straightforward – you simply add a comment block before each method describing what it does. Although there's no set list of things a comment should include, it's generally a good idea to describe the arguments a method takes, its return values and any exceptions. Providing an example can also be useful.
To do this in a machine-readable way, YARD provides a number of tags to help markup your comment, like
Let's go ahead and document our lone public method.
And that's all there is too it, nice and easy. Now that we've added the YARD comments, we can automatically generate some nice HTML documentation for publication on the web. Run the following command in your gem directory.
You should see a directory called
doc being generated in the root folder of our gem. Open up
doc\index.html in your browser and take a look around – don't miss the
Method List link in the top right to see how the comment we just added is being rendered. Pretty neat, hey?
As a side note, because this HTML documentation is automatically generated based on other files in our gem, it doesn't make sense to include it in version control. Open up the hidden
.gitignore file in the gem directory and check that it includes a
doc/ line, instructing Git to ignore the contents.
Let's commit our changes.
As a second side note, if you rebuild and reinstall the gem on your local machine, you can also view the documentation from the terminal using the
Our simple gem is now tested, documented, and ready to share with the outside world. In the final tutorial we'll look at how to publish our gem on Rubygems.org, handle changes and versioning of our gem in a sensible way, and also add an executable so we can use our gem on the command line, outside of IRB.
You can find the full source code for this gem on GitHub.