How to write unit tests dealing with files

I have written quite some Ruby code recently which worked with files in a file system somehow. Reading, writing, manipulating data stored in a file, or in a set of files in a directory, or in a set of directories, or one of the countless variations of this. There is a lot of code like this, and one question always is: How do I write unit tests for this code?

You need test files as input for tests. You need space to write files, which is cleaned up after the test. You often have series of tests which use similar but not quite identical sets of files. Doing all this in unit tests is inconvenient, as you usually can't just do it in the test code, but have to interface with some actual file system.

One approach is to stub all the interfaces dealing with the file system and fake them with test code, which mirrors the desired environment without ever hitting a real file system. FakeFS is one low-level way of doing this. You can also often do something similar on a higher level stubbing functions of your own code, when interaction with the file system is well encapsulated.

But this approach often is too limited. When you are using external libraries or calling external tools, you don't have access to the code interacting with the file system, so you can't stub it. You also limit your test coverage, as the actual interaction with the file system usually is an essential part. Finally it can be quite some work to isolate, separate, and fake the code, which interacts with files.

So we do want to have a better solution, right?

My solution is GivenFilesystem. It is a set of helpers for use in RSpec-based tests. It also provides a basic class, if you prefer more direct access or want to integrate it with some other test framework.

GivenFilesystem provides a simple and convenient way to create test files and directories. These can be structures as complex as needed. They are built up from test data you store as part of your tests. But you only need to store the data once, and create different scenarios using this data in your unit test code. GivenFilesystem also provides an easy way to create temporary locations in the file system for writing files. These are automatically cleaned up after the tests.

Here is an example of some code creating test files (see the details in the docs):

path = given_directory "mydir" do
  given_directory "one" do
    given_file "myfile"
    given_file "myotherfile"
  end
  given_directory "two" do
    given_file "myfile2", :from => "myfile"
  end
end

The only assumption is that you have a way to specify the path your code uses to read and write files. There is no magic behind the scenes, which replaces internal code accessing the file system, but your code has to be structured in a way that you can tell it where files are. Usually this is something you want to have anyway, and which gives nicely structured code.

So if you come to the point, where you need to set up files for unit tests, or worry about cleaning up files written by your tests, consider giving GivenFilesystem a try. It has made my life a little bit more simple and convenient, maybe it can do the same for you.

I put some effort into polishing GivenFilesystem. It comes with tests, has full test coverage, and clean code. This turned out quite nicely, also thanks to the magic of code review.

Get the gem, read the docs, get started.

Feedback and other contributions are always welcome. Or if you just want to talk about it, simply drop me an email.