.NET 1.1+

NUnit String Assertions

by Richard Carr, published at http://www.blackwasp.co.uk/StringAssert.aspx

The assertions provided by the NUnit framework's Assert class are sufficient to test any code. However, NUnit does provide other assertion classes, which can make tests more readable. Once such class includes assertions for strings.

StringAssert

When you are developing tests that check that a string is correctly formed, you could use the methods of the string class along with simple NUnit assertions. To improve the readability of your test code, NUnit includes a set of assertions that are designed to be used with strings. These are found in the StringAssert class.

StringAssert contains six static methods. Each allows you to assert that the contents of a string are as expected. You can ensure that a string contains a given substring, compare two strings whilst ignoring their case and check that a string matches a specific regular expression. In this article we'll look at all of the methods.

Contains

The first assertion that we'll consider is Contains. As the name suggests, this method asserts that one string contains another. The first parameter receives the text that must be present. The second argument is used to supply the string being examined. The assertion will pass if the first string can be found anywhere within the second.

The following test demonstrates this. Here we are checking that an error message builder class creates messages that contain the item that was at fault.

[Test]
public void AConstructedErrorContainsTheFaultingItemName()
{
    IErrorBuilder builder = new ErrorBuilder();
    string faultingItem = "Faulting Item";

    string errorMessage = builder.BuildError(faultingItem);

    StringAssert.Contains(faultingItem, errorMessage);
}

NB: As with other assertions, there is an overloaded version of this, and all other StringAssert methods, which permits you to include a message for display when the test fails.

StartsWith and EndsWith

StartsWith and EndsWith provide similar functionality to Contains. The key difference is the position at which the substring must appear. StartsWith only passes if the first string is fully contained within the second and begins at index zero. EndsWith passes only when the substring appears at the end of the second string, with no other characters following it.

The next two sample tests show the use of these assertions. The first test ensures that our error messages start with the word, "Error". The second tests that the error message ends with a full stop, or period.

[Test]
public void AConstructedErrorStartsWithTheWordError()
{
    IErrorBuilder builder = new ErrorBuilder();
    string faultingItem = "Faulting Item";

    string errorMessage = builder.BuildError(faultingItem);

    StringAssert.StartsWith("Error", errorMessage);
}

[Test]
public void AConstructedErrorHasCorrectPunctuation()
{
    IErrorBuilder builder = new ErrorBuilder();
    string faultingItem = "Faulting Item";

    string errorMessage = builder.BuildError(faultingItem);

    StringAssert.EndsWith(".", errorMessage);
}

AreEqualIgnoringCase / AreNotEqualIgnoringCase

If you want to ensure that two strings are identical, you can use the standard method, Assert.AreEqual. Sometimes you'll want to allow two strings to match, even if they have different capitalisation. In these cases you can use the AreEqualIgnoringCase assertion. This passes for two strings that differ only in case. To ensure that two strings are not a match, you can use AreNotEqualIgnoringCase.

The following example checks the full error message in a case-insensitive manner.

[Test]
public void AConstructedErrorIsCorrectlyFormed()
{
    IErrorBuilder builder = new ErrorBuilder();
    string faultingItem = "Faulting Item";

    string errorMessage = builder.BuildError(faultingItem);

    StringAssert.AreEqualIgnoringCase("error in faulting item.", errorMessage);
}

IsMatch

The final StringAssert method is the most flexible of the string-based assertions but, potentially, the one that is least likely to be quickly read and understood. It asserts that a string is a match with a regular expression. The regular expression is provided as the first argument and the string to match as the second. If there is a match, the assertion passes.

The final example uses this assertion against a class that captures the IP address of the computer. This test checks that the returned IP address is in the expected format. NB: This regular expression matches invalid IP addresses if they are of the expected dot-decimal notation but with field values greater than 255.

[Test]
public void ACapturedIPAddressIsCorrectlyFormatted()
{
    IIPCapturer capturer = new IPCapturer();

    string ipAddress = capturer.BuildIPAddress();

    StringAssert.IsMatch(@"\b(?:\d{1,3}\.){3}\d{1,3}\b", ipAddress);
}