hamlest – matchers for lest

hamlest provides matchers for the tiny C++11 test helper lest [1]. hamlest's design is inspired on the C++ version of hamcrest by Jon Reid [2,3] and on ideas found in PyHamcrest [4].

Let writing tests become irresistibly easy and attractive.

Contents

• Example usage
• Compile and run
• Synopsis
• Reported to work with
• Other libraries
• Notes and References

Example usage

#include "hamlest.hpp"
#include <set>

using namespace lest::hamlest;

std::set<int> s{ 1, 2, 3, };
std::set<int> t{ 2, 1, 0, };

std::string hello() { return "hello C++11 world"; }

const lest::test specification[] =
{
    CASE("sets of int compare equal")
    {
        EXPECT( s == s );
        EXPECT( s == t );
    },

    CASE("sets of int match equal")
    {
        EXPECT_THAT( s, equal_to( s ) );
        EXPECT_THAT( s, equal_to( t ) );
    },

    CASE("string contains substring")
    {
        EXPECT_THAT( hello(), starts_with( "hello" ) );
        EXPECT_THAT( hello(), ends_with( "world" ) );
        EXPECT_THAT( hello(), contains( "C++11" ) );
        EXPECT_THAT( hello(), contains( "C++14" ) );
    },

    CASE("string matches at least one string")
    {
        EXPECT_THAT( "hello", any_of( { "hello", "C++", "world" } ) );
        EXPECT_THAT( "hello", any_of( { "foo"  , "C++", "bar"   } ) );
    },

    CASE("string satisfies all constraints")
    {
        EXPECT_THAT( hello(), all_of( starts_with("hello"), contains("C++11"), ends_with("world") ) );
        EXPECT_THAT( hello(), all_of( starts_with("hello"), contains("C++14"), ends_with("world") ) );
    },
};

int main()
{
    return lest::run( specification );
}

Compile and run

For ease of use, the decompose version of lest is included in this repository.

prompt>g++ -Wall -Wextra -Weffc++ -std=c++11 -o example1.exe example1.cpp && example1.exe
example1.cpp:25: failed: sets of int compare equal: s == t for { 1, 2, 3, } == { 0, 1, 2, }
example1.cpp:31: failed: sets of int match equal: s equal_to( t ) for { 1, 2, 3, } is equal to { 0, 1, 2, }
example1.cpp:39: failed: string contains substring: hello() contains( "C++14" ) for "hello C++11 world" contains "C++14"
example1.cpp:45: failed: string matches at least one string: "hello" any_of( { "foo" , "C++", "bar" } ) \
                         for "hello" (is_equal to "foo" or is equal to "C++" or is equal to "bar")
example1.cpp:51: failed: string satisfies all constraints: hello() all_of( starts_with("hello"), contains("C++14"), ends_with("world") ) \
                         for "hello C++11 world" (starts with "hello" and contains "C++14" and ends with "world")
5 out of 5 tests failed.

Synopsis

Assertions Macros

EXPECT_THAT( expr, matcher )
Match the expression and report failure. If an exception is thrown it is caught, reported and counted as a failure.

If an assertion fails, the remainder of the test that assertion is part of is skipped.

Note that EXPECT_THAT() is a shortened alias for lest_EXPECT_THAT().

Other Macros

lest_NO_SHORT_ASSERTION_NAMES
Define this to omit the shortened alias macros for the lest_EXPECT... macros.

Namespaces

namespace lest
Types and functions are located in namespace lest.

namespace lest::hamlest
Matcher functions to pull in.

Matchers

Object

same_instance - match same object

Numeric

close_to - match number within a range delta, e.g. close_to(10, 2)
equal_to - match equal, e.g. equal_to('a'), equal_to(vec)
not_equal_to - match not equal, e.g. not_equal_to("hello")
less_than - match less than, e.g. less_than(42)
less_equal - match less than or equal to, e.g. less_equal(42)
greater_than - match greater than, e.g. greater_than(42)
greater_equal - match greater than or equal to, e.g. greater_equal(42)

Textual

starts_with - match the start of a string, e.g. starts_with("hello")
ends_with - match the end of a string, e.g. ends_with("world")
contains - match part of a string, , e.g. contains("C++11")
contains_regexp - match part of string (excluded from test: fails with Clang 3.2 and GNUC 4.8.1)
matches_regexp - match whole string

Sequence

contains - match a sequence in a container, e.g. contains(3), contains({3,4})
contains_elements - match individual elements in container, e.g. contains_elements({3,4})
is_empty - match empty container, e.g. is_empty()
size_is - match size of a container, e.g. size_is(2), size_is(less_than(3))
Note: currently sequence matchers cannot be wrapped in logical matchers.

Logical

anything - [a, an ?] match anything; takes optional description, e.g. anything<int>()
is - decorate matcher to improve readability, or match a value, e.g. is(42)
is_not - negate the matcher, e.g. is_not(close_to(42,1))
all_of - and all matchers, or match all values in initialiser list
any_of - or all matchers, or match any value in initialiser list

Reported to work with

• g++ 4.8.1
• clang 3.2
• (for lest: Visual Studio 2013 preview)

Other libraries

Google C++ Mocking Framework, gmock - This framework has a rich set of matchers and actions [5].

Notes and References

[1] lest – lest errors escape testing.

[2] hamcrest on Google Code.

[3] hamcrest C++ by Jon Reid on Google Code.

[4] PyHamcrest on GitHub

[5] Google C++ Mocking Framework on Google Code.