The
expectations framework provides the ability to create
interaction (or behavior) based tests. I've previously written about adding
interaction based testing to expectations; however, the examples from that blog entry focused exclusively on testing interactions where each argument is matched using equality. In this entry I'll give examples of how each argument can be also be verified using a class, regex, exception, or a custom function.
When writing
state based tests using expectations the type of test you're writing is inferred from the expected value. If the expected value is a regex, expectations will test the actual value to see if it matches the regex. If you passed in a class, expectations will test the actual value to see if it's an instance of that class. If you passed in an exception... you get the idea. All of what I said above, is also true for arguments of an interaction.
Let's start with a simple interaction based test:
In the example above, we're calling the spit function with exactly the arguments that we've specified in our test. This test will pass; however, we've had to specify the exact file location and the exact data. If for some reason you can't specify exactly what the argument will be, it's nice to have a way to specify as much as you possibly can.
In the example below, we're still specifying the exact data, but we're only verifying that the file is somewhere in /tmp/.
As I previously mentioned, we can also get more general and only verify the class of an argument. For example, if we knew our data was going to be a String, but we didn't want to specify exactly what that string was, the following test would do the trick.
While expectations provides you with a lot of default options, there are times when you'll want to write your own argument "matcher". As a contrived example, let's pretend that we want to test that the last argument is true or nil.
One of the best features of expectations is it's error reporting, and the same error reporting logic is applied to arguments when an interaction based test fails. Given the example above, you'll get the following error message.
failure in (success_examples.clj:204) : success.success-examples
expected: (spit #"/tmp/" String :append true-or-nil?)
got: 0 times
-- got: (spit "/tmp/somewhere-else" "nil")
"nil", "/tmp/somewhere-else" are in actual, but not in expected
true_or_nil_QMARK, #"/tmp/", :append, String are in expected, but not in actual
expected is larger than actual
-- got: (spit "/tmp/hello-world" "some data" :append "s")
- arg4: not true or nil
As you can see both calls are reported, and each argument has a detailed report (if it did not match).
Finally, expectations provides and additional function that can be used to verify that certain key/value pairs are in an argument. The following example doesn't really make sense, since you'd never want to pass a map as the last argument to spit, but it's easy to follow in the context of this blog entry.
In the above example, (contains-kvs) is used to verify that the final argument to spit contains the key/value pairs :a :b :c :d.
I hope that interaction arg matching follows the principle of least surprise, since it behaves the same as expectations state based tests. I also hope that the ability to use an arbitrary function for verification will provide any necessary flexibility. If you're using expectations, give it a try and let me know.
