Rubberduck.Fakes Gets an Upgrade

One of the objectively coolest features in Rubberduck is the Fakes API. Code that pops a MsgBox for example, needs a way to work without actually popping that message box, otherwise that code cannot be unit tested… without somehow hijacking the MsgBox function. The Fakes API does exactly that: it hooks into the VBA runtime, intercepts specific internal function calls, and makes it return exactly what your test setup …set up.

This API can stop time, or Now can be told to return 1:59AM on first invocation, 1:00AM on the next, and then we can test and assert that some time-sensitive logic survives a daylight savings time toggle, or how Timer-dependent code behaves at midnight.

Let’s take a look at the members of the IFakesProvider interface.

Fakes Provider

Fakes for many of the internal VBA standard library functions exist since the initial release of the feature, although some providers wouldn’t always play nicely together – thanks to a recent pull request from @tommy9 these issues have been resolved, and a merry bunch of additional implementations are now available in pre-release builds:

Name	Description	Parameter names
MsgBox	Configures VBA.Interaction.MsgBox calls	Fakes.Params.MsgBox
InputBox	Configures VBA.Interaction.InputBox calls	Fakes.Params.InputBox
Beep	Configures VBA.Interaction.Beep calls
Environ	Configures VBA.Interaction.Environ calls	Fakes.Params.Environ
Timer	Configures VBA.DateTime.Timer calls
DoEvents	Configures VBA.Interaction.DoEvents calls
Shell	Configures VBA.Interaction.Shell calls	Fakes.Params.Shell
SendKeys	Configures VBA.Interaction.SendKeys calls	Fakes.Params.SendKeys
Kill	Configures VBA.FileSystem.Kill calls	Fakes.Params.Kill
MkDir	Configures VBA.FileSystem.MkDir calls	Fakes.Params.MkDir
RmDir	Configures VBA.FileSystem.RmDir calls	Fakes.Params.RmDir
ChDir	Configures VBA.FileSystem.ChDir calls	Fakes.Params.ChDir
ChDrive	Configures VBA.FileSystem.ChDrive calls	Fakes.Params.ChDrive
CurDir	Configures VBA.FileSystem.CurDir calls	Fakes.Params.CurDir
Now	Configures VBA.DateTime.Now calls
Time	Configures VBA.DateTime.Time calls
Date	Configures VBA.DateTime.Date calls
Rnd*	Configures VBA.Math.Rnd calls	Fakes.Params.Rnd
DeleteSetting*	Configures VBA.Interaction.DeleteSetting calls	Fakes.Params.DeleteSetting
SaveSetting*	Configures VBA.Interaction.SaveSetting calls	Fakes.Params.SaveSetting
Randomize*	Configures VBA.Math.Randomize calls	Fakes.Params.Randomize
GetAllSettings*	Configures VBA.Interaction.GetAllSettings calls
SetAttr*	Configures VBA.FileSystem.SetAttr calls	Fakes.Params.SetAttr
GetAttr*	Configures VBA.FileSystem.GetAttr calls	Fakes.Params.GetAttr
FileLen*	Configures VBA.FileSystem.FileLen calls	Fakes.Params.FileLen
FileDateTime*	Configures VBA.FileSystem.FileDateTime calls	Fakes.Params.FileDateTime
FreeFile*	Configures VBA.FileSystem.FreeFile calls	Fakes.Params.FreeFile
IMEStatus*	Configures VBA.Information.IMEStatus calls
Dir*	Configures VBA.FileSystem.Dir calls	Fakes.Params.Dir
FileCopy*	Configures VBA.FileSystem.FileCopy calls	Fakes.Params.FileCopy

*Members marked with an asterisk are only available in pre-release builds for now.

Parameter Names

The IVerify.ParameterXyz members make a unit test fail if the specified parameter wasn’t given a specified value, but the parameter names must be passed as strings. This is a UX issue: the API essentially requires hard-coded magic string literals in its users’ code; this is obviously error-prone and feels a bit arcane to use. The IFakesProvider interface has been given a Params property that gets an instance of a class that exposes the parameter names for each of the IFake implementations, as shown in the list above, and the screenshot below:

^{Picking the correct parameter name from a drop-down completion list beats risking a typo, doesn’t it?}

Note: the PR for this feature has not yet been merged at the time of this writing.

Testing Without Fakes (aka Testing with Stubs)

Unit tests have a 3-part structure: first we arrange the test, then we act by invoking the method we want to test; lastly, we assert that an actual result matches the expectations. When using fakes, we configure them in the arrange part of the test, and in the assert part we can verify whether (and/or how many times) a particular method was invoked with a particular parameterization.

Let’s say we had a procedure we wanted to write some tests for:

Public Sub TestMe()
    If MsgBox("Print random number?", vbYesNo + vbQuestion, "Test") = vbYes Then
        Debug.Print Now & vbTab & Rnd * 42
    Else
        Debug.Print Now
    End If
End Sub

If we wanted to make this logic fully testable without the Fakes API, we would need to inject (likely as parameters) abstractions for MsgBox, Now, and Debug dependencies: instead of invoking MsgBox directly, the procedure would be invoking the Prompt method of an interface/class that wraps the MsgBox functionality. Unit tests would need a stub implementation of that interface in order to allow some level of configuration setup – an invocation counter, for example. A fully testable version of the above code might then look like this:

Public Sub TestMe(ByVal MessageBox As IMsgBox, ByVal Random As IRnd, ByVal DateTime As IDateTime, ByVal Logger As ILogger)
    If MessageBox.Prompt("Print random number?", "Test") = vbYes Then
        Logger.LogDebug DateTime.Now & vbTab & Random.Next * 42
    Else
        Logger.LogDebug DateTime.Now
    End If
End Sub

The method is testable, because the caller controls all the dependencies. We’re probably injecting an IMsgBox that pops a MsgBox, an IRnd that wraps Rnd, a DateTime parameter that returns VBA.DateTime.Now and an ILogger that writes to the debug pane, but we don’t know any of that. I fact, we could very well run this method with an ILogger that writes to some log file or even to a database; the IRnd implementation could consistently be returning 0.4 on every call, IDateTime.Now could return Now adjusted to UTC, and IMsgBox might actually display a fancy custom modal UserForm dialog – either way, TestMe doesn’t need to change for any of that to happen: it does what it needs to do, in this case fetching the next random number and outputting it along with the current date/time if a user prompt is answered with a “Yes”, otherwise just output the current date/time. It’s the interfaces that provide the abstraction that’s necessary to decouple the dependencies from the logic we want to test. We could implement these interfaces with stubs that simply count the number of times each member is invoked, and the logic we’re testing would still hold.

We could then write tests that validate the conditional logic:

'@TestMethod
Public Sub TestMe_WhenPromptYes_GetsNextRandomValue()
    ' Arrange
    Dim MsgBoxStub As StubMsgBox ' implements IMsgBox, but we want the stub functionality here
    Set MsgBoxStub = New StubMsgBox
    MsgBoxStub.Returns vbYes
    Dim RndStub As StubRnd ' implements IRnd, but we want the stub functionality here too
    Set RndStub = New StubRnd
    ' Act
    Module1.TestMe MsgBoxStub, RndStub, New DateTimeStub, New LoggerStub
    ' Assert
    Assert.Equals 1, RndStub.InvokeCount
End Sub
'@TestMethod
Public Sub TestMe_WhenPromptNo_DoesNotGetNextRandomValue()
    ' Arrange
    Dim MsgBoxStub As StubMsgBox
    Set MsgBoxStub = New StubMsgBox
    MsgBoxStub.Returns vbNo
    Dim RndStub As StubRnd
    Set RndStub = New StubRnd
    ' Act
    Module1.TestMe MsgBoxStub, RndStub, New DateTimeStub, New LoggerStub
    ' Assert
    Assert.Equals 0, RndStub.InvokeCount
End Sub

These stub implementations are class modules that need to be written to support such tests. StubMsgBox would implement IMsgBox and expose a public Returns method to configure its return value; StubRnd would implement IRnd and expose a public InvokeCount property that returns the number of times the IRnd.Next method was called. In other words, it’s quite a bit of boilerplate code that we’d usually rather not need to write.

Let’s see how using the Fakes API changes that.

Using Rubberduck.FakesProvider

The standard test module template defines Assert and Fakes private fields. When early-bound (needs a reference to the Rubberduck type library), the declarations and initialization look like this:

'@TestModule
Option Explicit
Option Private Module
Private Assert As Rubberduck.AssertClass
Private Fakes As Rubberduck.FakesProvider
'@ModuleInitialize
Public Sub ModuleInitialize()
    Set Assert = CreateObject("Rubberduck.AssertClass")
    Set Fakes = CreateObject("Rubberduck.FakesProvider")
End Sub

The Fakes API implements three of the four stubs for us, so we still need an implementation for ILogger, but now the method remains fully testable even with direct MsgBox, Now and Rnd calls:

Public Sub TestMe(ILogger Logger)
    If MsgBox("Print random number?", vbYesNo + vbQuestion, "Test") = vbYes Then
        Logger.LogDebug Now & vbTab & Rnd * 42
    Else
        Logger.LogDebug Now
    End If
End Sub

With an ILogger stub we could write a test that validates what’s being logged in each conditional branch (or we could decide that we don’t need an ILogger interface and we’re fine with tests actually writing to the debug pane, and leave Debug.Print statements in place), but let’s just stick with the same two tests we wrote above without the Fakes API. They look like this now:

'@TestMethod
Public Sub TestMe_WhenPromptYes_GetsNextRandomValue()
    
    ' Arrange
    Fakes.MsgBox.Returns vbYes
    ' Act
    Module1.TestMe New LoggerStub ' ILogger is irrelevant for this test
    ' Assert
    Fakes.Rnd.Verify.Once
End Sub
'@TestMethod
Public Sub TestMe_WhenPromptNo_DoesNotGetNextRandomValue()
    
    ' Arrange
    Fakes.MsgBox.Returns vbNo
    ' Act
    Module1.TestMe New LoggerStub ' ILogger is irrelevant for this test
    ' Assert
    Fakes.Rnd.Verify.Never
End Sub 

We configure the MsgBox fake to return the value we need, we invoke the method under test, and then we verify that the Rnd fake was invoked once or never, depending on what we’re testing. A failed verification will fail the test the same as a failed Assert call.

The fakes automatically track invocations, and remember what parameter values each invocation was made with. Setup can optionally supply an invocation number (1-based) to configure specific invocations, and verification can be made against specific invocation numbers as well, and we could have a failing test that validates whether Randomize is invoked when Rnd is called.

API Details

The IFake interface exposes members for the setup/configuration of fakes:

Name	Description
AssignsByRef	Configures the fake such as an invocation assigns the specified value to the specified ByRef argument.
Passthrough	Gets/sets whether invocations should pass through to the native call.
RaisesError	Configures the fake such as an invocation raises the specified run-time error.
Returns	Configures the fake such as the specified invocation returns the specified value.
ReturnsWhen	Configures the fake such as the specified invocation returns the specified value given a specific parameter value.
Verify	Gets an interface for verifying invocations performed during the test. See IVerify.

^{The members of Rubberduck.IFake}

The IVerify interface exposes members for verifying what happened during the “Act” phase of the test:

Name	Description
AtLeast	Verifies that the faked procedure was called a specified minimum number of times.
AtLeastOnce	Verifies that the faked procedure was called one or more times.
AtMost	Verifies that the faked procedure was called a specified maximum number of times.
AtMostOnce	Verifies that the faked procedure was not called or was only called once.
Between	Verifies that the number of times the faked procedure was called falls within the supplied range.
Exactly	Verifies that the faked procedure was called a specified number of times.
Never	Verifies that the faked procedure was called exactly 0 times.
Once	Verifies that the faked procedure was called exactly one time.
Parameter	Verifies that the value of a given parameter to the faked procedure matches a specific value.
ParameterInRange	Verifies that the value of a given parameter to the faked procedure falls within a specified range.
ParameterIsPassed	Verifies that an optional parameter was passed to the faked procedure. The value is not evaluated.
ParameterIsType	Verifies that the passed value of a given parameter was of a type that matches the given type name.

^{The members of Rubberduck.IVerify}

There’s also an IStub interface: it’s a subset of IFake, without the Returns setup methods. Thus, IStub is used for faking Sub procedures, and IFake for Function and Property procedures.

---

When to Stub Standard Library Members

Members of VBA.FileSystem not covered include EOF and LOF functions, Loc, Seek, and Reset. VBA I/O keywords Name, Open, and Close operate at a lower level than the standard library and aren’t covered, either. VBA.Interaction.CreateObject and VBA.Interaction.GetObject, VBA.Interaction.AppActivate, VBA.Interaction.CallByName, and the hidden VBA.Interaction.MacScript function, aren’t implemented.

Perhaps CreateObject and GetObject calls belong behind an abstract factory and a provider interface, respectively, and perhaps CallByName doesn’t really need hooking anyway. In any case there are a number of file I/O operations that cannot be faked and demand an abstraction layer between the I/O work and the code that commands it: that’s when you’re going to want to write stub implementations.

If you’re writing a macro that makes an HTTP request and processes its response, consider abstracting the HttpClient stuff behind an interface (something like Function HttpGet(ByVal Url As String)): the macro code will gain in readability and focus, and then if you inject that interface as a parameter, then a unit test can inject a stub implementation for it, and you can write tests that handle (or not?) an HTTP client error, or process such or such JSON or HTML payload – without hitting any actual network and making any actual HTTP requests.

Until we can do mocking with Rubberduck, writing test stubs for our system-boundary interfaces is going to have to be it. Mocking would remove the need to explicitly implement most test stubs, by enabling the same kind of customization as with fakes, but with your own interfaces/classes. Or Excel’s. Or anything, in theory.

---