2.2　Hamcrest对象匹配器详解

在了解了Hamcrest及其优点之后，本节将深入掌握Hamcrest所提供的各类灵活且强大的对象匹配器的用法。总体来说，Hamcrest的对象匹配器大致可以分为如下几类。

• org.hamcrest.beans：对象实例和对象属性相关的匹配器，其底层使用的是Property-Descriptor相关的API。
• org.hamcrest.collection：Java容器和元素关系相关的匹配器。
• org.hamcrest.number：Double及BigDecimal相关的匹配器。
• org.hamcrest.object：Object对象相关的匹配器（由于对象匹配器比较简单，因此本节不做讲解）。
• org.hamcrest.text：文本字符相关的匹配器。
• org.hamcrest.xml：XML文档相关的匹配器。
• org.hamcrest.core：核心匹配器，比如is、not、equalTo、anyOf、allOf等都属于这类匹配器，也是使用最多的对象匹配器。

2.2.1　org.hamcrest.core

核心匹配器是应用范围最广泛的一组匹配器，JUnit 4.4以后的版本默认依赖Hamcrest的核心匹配器。大多数情况下，核心匹配器其实已能足够应对日常工作的需要了。在使用核心匹配器时，建议大家通过静态导入的方式，将所有核心匹配器引入单元测试类中，具体做法如下。

import static org.hamcrest.CoreMatchers.*;
import static org.hamcrest.MatcherAssert.assertThat;

核心匹配器相对来说比较多（如图2-7所示），限于篇幅，本节无法讲解所有匹配器的具体用法，因此这里只是挑选介绍几个逻辑相关的匹配器，其他的匹配器将在示例代码中进行介绍，比如，Mockito和Powermock中都会讲解核心匹配器的使用。

图2-7　Hamcrest核心匹配器列表

1）allOf：只有当所有的匹配条件都满足时，断言才能成功。

@Test
public void testAllOf()
{
    String actually = "Hello Hamcrest";
    //只有当下列匹配条件都满足时，才能断言成功。
    //actually与"Hello Hamcrest"的值相同（equal）。
    assertThat(actually, allOf(is(equalTo("Hello Hamcrest")),
            //actually中包含字符串"llo Ha"。
            containsString("llo Ha"),
            //actually是以"Hello"开头的。
            startsWith("Hello"),
            //actually是以"crest"结尾的。
            endsWith("crest"),
            //actually是String类型的一个实例。
            instanceOf(String.class),
            //actually不为null。
            notNullValue(),
            stringContainsInOrder("Hello", "Hamcrest"))
    );
    //与上面的写法等价，将allOf方法传入匹配器List。
    assertThat(actually, allOf(Arrays.asList(
            //actually与"Hello Hamcrest"的值相同（equal）。
            is(equalTo("Hello Hamcrest")),
            //actually中包含字符串"llo Ha"。
            containsString("llo Ha"),
            //actually是以"Hello"开头的。
            startsWith("Hello"),
            //actually是以"crest"结尾的。
            endsWith("crest"),
            //actually是String类型的一个实例。
            instanceOf(String.class),
            //actually不为null。
            notNullValue(),
            stringContainsInOrder("Hello", "Hamcrest")))
    );

在上述示例代码中，只有当所有的条件匹配都是符合期望的，断言才能够成功。allOf方法提供了两种重载形式，Matcher的可变长数组和Iterable<Matcher>，具体形式如下。

• allOf(java.lang.Iterable<org.hamcrest.Matcher<? super T>> matchers)
• allOf(org.hamcrest.Matcher<? super T>... matchers)

2）anyOf：若有任意一个匹配条件成立，则断言成功。

@Test
public void testAnyOf()
{
    String actually = "Hello Hamcrest";
    //下列匹配条件只要有一个满足，则断言成功。
    //actually与"Hello Hamcrest1"的值相同（equal）。 ×
    assertThat(actually, anyOf(is(equalTo("Hello Hamcrest1")),
            //actually中包含字符串"llo Xa"。 ×
            containsString("llo Ha"),
            //actually是以"Hello"开头的。 √
            startsWith("Hello"),
            //actually是以"crest"结尾的。 ×
            endsWith("crest?"),
            //actually是Integer类型的一个实例。 ×
            instanceOf(Integer.class),
            //actually不为null。 ×
            nullValue(),
            //顺序错误。 ×
            stringContainsInOrder("Hamcrest", "Hello"))
    );
    //与上面的写法等价。

        assertThat(actually, anyOf(Arrays.asList(
       //actually与"Hello Hamcrest1"的值相同（equal）。 ×
            is(equalTo("Hello Hamcrest1")),
            //actually中包含字符串"llo Xa"。 ×
            containsString("llo Ha"),
            //actually是以"Hello"开头的。 √
            startsWith("Hello"),
            //actually是以"crest"结尾的。 ×
            endsWith("crest?"),
            //actually是Integer类型的一个实例。 ×
            instanceOf(Integer.class),
            //actually不为null。 ×
            nullValue(),
            //顺序错误。 ×
            stringContainsInOrder("Hamcrest", "Hello")))
    );
}

在上面的代码中，只有“Hello Hamcrest”以“Hello”开头是正确的，其他的条件匹配都不成立，但是这并不妨碍断言的最终成功。anyOf方法提供了两种重载形式，具体如下所示。

• anyOf(java.lang.Iterable<org.hamcrest.Matcher<? super T>> matchers)
• anyOf(org.hamcrest.Matcher<? super T>... matchers)

3）both：两个匹配条件的逻辑“与”。

@Test
public void testBoth()
{
    String actually = "Hello Hamcrest";
    assertThat(actually, both(
            allOf(
                    //actually与"Hello Hamcrest"的值相等（equal）。
                    is(equalTo("Hello Hamcrest")),
                    //actually中包含字符串"llo Ha"。
                    containsString("llo Ha"),
                    //actually是以"Hello"开头的。
                    startsWith("Hello"),
                    //actually是以"crest"结尾的。
                    endsWith("crest"))
            ).and(
                allOf(
                    instanceOf(String.class),
                    //actually不为null。
                    notNullValue(),
                    //顺序正确。
                    stringContainsInOrder("Hello", "Hamcrest")
                )
            )
    );
}

上面这段代码稍微有些复杂，但只需要重点关注both().and()语法即可，该语法能够很好地支持both方法和and方法中的对象匹配器，这也是Hamcrest语法的强大之处，不同的Matcher可以实现非常灵活的组合。

4）either：两个匹配条件的逻辑“或”。

@Test
public void testEither()
{
    String actually = "Hello Hamcrest";
    //与"Hello Hamcrest"相等或为null，只要满足一个匹配条件即可断言成功。
    assertThat(actually, either(is(equalTo("Hello Hamcrest"))).or(nullValue()));
}

5）语法糖方法：为了使单元测试方法更具可读性，Hamcrest还提供了很多语法糖方法。比如，equalTo与is(equalTo(...))本身是没有任何区别的，这么做的目的只是为了提高可读性，是一种更具陈述性的表达方式。

2.2.2　org.hamcrest.beans

如果想要判断某个对象O中是否包含属性P、P的值为X，以及两个对象O是否拥有相同的属性，并且每一个属性的值都相等，则可以使用beans下的对象匹配器。比如，使用ORM（Object Relational Mapping，对象关系映射）框架从数据库中获取某个Entity对象，或者调用一个远程方法返回Entity对象时，没有必要在获取对象的每一个实例属性后都进行断言操作，直接通过beans中相关的对象匹配器就可以完成判断。具体实现代码如程序代码2-6所示。

程序代码2-6　org.hamcrest.beans匹配器示例

//这里省略部分代码。
public class SimpleBean
{
    private String name;
    private int age;

    public SimpleBean()
    {
    }

    public SimpleBean(String name, int age)
    {
        this.name = name;
        this.age = age;
    }
//这里省略get和set方法。
}
//下面是单元测试的相关代码，其中包含了beans下匹配器的用法示例。
import org.junit.Test;

import static org.hamcrest.CoreMatchers.equalTo;
import static org.hamcrest.CoreMatchers.is;
import static org.hamcrest.MatcherAssert.assertThat;
import static org.hamcrest.Matchers.hasProperty;
import static org.hamcrest.Matchers.samePropertyValuesAs;

public class HamcrestUsageTest
{
    @Test
    public void testHasProperty()
    {
        final SimpleBean bean = new SimpleBean();
        //断言bean中包含属性name。
        assertThat(bean, hasProperty("name"));
    }

    @Test
    public void testHasPropertyWithValue()
    {
        final SimpleBean bean = new SimpleBean("Alex", 35);
        //断言bean中包含属性及期望值。
        assertThat(bean, hasProperty("name", is(equalTo("Alex"))));
        assertThat(bean, hasProperty("age", is(equalTo(35))));
    }

    @Test
    public void testSamePropertyValuesAs()
    {
        final SimpleBean bean1 = new SimpleBean("Alex", 35);
        final SimpleBean bean2 = new SimpleBean("Alex", 35);
        final SimpleBean bean3 = new SimpleBean("Alex", 100);
        //断言bean1和bean2具有相同的属性，并且每个属性值都相等。
        assertThat(bean1, samePropertyValuesAs(bean2));
        //断言bean1和bean3具有相同的属性，并且属性值都相等（忽略对age属性的比较，因为age不相等）。
        assertThat(bean1, samePropertyValuesAs(bean3, "age"));
    }
}

2.2.3　org.hamcrest.collection

collection下的对象匹配器主要用于匹配元素、数组与collection、map之间的关系，下面通过示例代码（关于匹配器的相关信息，代码注释进行了详细描述）进行讲解。

1）IsArray<T>：匹配数组中所有元素的匹配器。

@Test
public void testIsArray()
{
    Integer[] actually = {1, 2, 3};
    //断言匹配actually数组中的元素个数及内容。
    assertThat(actually, is(array(equalTo(1), equalTo(2), equalTo(3))));
    //下面的断言匹配会失败，因为匹配器的顺序与actually 中元素的顺序不一致。
    //assertThat(actually, is(array(equalTo(1), equalTo(3), equalTo(2))));
}

2）IsArrayContaining<T>：匹配数组中是否包含某个元素。

@Test
public void testHasItemInArray()
{
    String[] actually = {"foo", "bar"};
    //断言匹配actually数组中包含元素“foo”。
    assertThat(actually, hasItemInArray(is("foo")));
    //断言匹配actually数组中包含以“ba”开头的元素。
    assertThat(actually, hasItemInArray(startsWith("ba")));
}

3）IsArrayWithSize<E>：匹配数组长度或数组为空。

@Test
public void testIsArrayWithSize()
{
    Integer[] actually = {1, 2, 3};
    //以下三种写法是等价的，都是用于断言匹配actually数组的长度。
    assertThat(actually, arrayWithSize(3));
    assertThat(actually, arrayWithSize(is(3)));
    assertThat(actually, arrayWithSize(equalTo(3)));

    //数组不为空。
    assertThat(actually, is(not(emptyArray())));
}

4）IsArrayContainingInOrder<E>：按顺序匹配数组中的所有元素。

@Test
public void testIsArrayContainingInOrder()
{
    Integer[] actually = {1, 2, 3};
    //断言匹配actually包含元素1、2、3（顺序要求与actually一致），以下三种写法是等价的。
    assertThat(actually, arrayContaining(1, 2, 3));
    assertThat(actually, arrayContaining(equalTo(1), equalTo(2), equalTo(3)));
    assertThat(actually,
    arrayContaining(
        Arrays.asList(equalTo(1), equalTo(2), equalTo(3)))
    );
}

5）IsArrayContainingInAnyOrder<E>：以任意顺序匹配数组中的所有元素。

@Test
public void testArrayContainingInAnyOrder()
{
    Integer[] actually = {1, 2, 3};
    //断言匹配actually是否包含元素1、2、3（允许任意顺序），以下三种写法是等价的。
    assertThat(actually, arrayContainingInAnyOrder(
        equalTo(1), equalTo(3), equalTo(2)));
    assertThat(actually, arrayContainingInAnyOrder(1, 3, 2));
    assertThat(actually, arrayContainingInAnyOrder(
        Arrays.asList(equalTo(1), equalTo(3), equalTo(2)))
    );
}

6）IsCollectionWithSize<E>：断言collection元素的个数。

@Test
public void testIsCollectionWithSize()
{
    Collection<Integer> actually = Arrays.asList(1, 2, 3);
    //断言匹配actually元素的个数，以下两种写法是等价的。
    assertThat(actually, hasSize(3));
    assertThat(actually, hasSize(equalTo(3)));
}

7）IsEmptyCollection<E>：断言collection为空的匹配器。

@Test
public void testIsEmptyCollection()
{
    Collection<Integer> actually = Collections.emptyList();
    //actually为空。
    assertThat(actually, empty());
    //actually为空，且actually中的元素类型为Integer。
    assertThat(actually, emptyCollectionOf(Integer.class));
}

8）IsEmptyIterable<E>：断言Iterable为空的匹配器。

@Test
public void testIsEmptyIterable()
{
    //Collection是Iterable的子接口。
    Collection<Integer> actually = Collections.emptyList();
    //actually为空。
    assertThat(actually, emptyIterable());
    //actually为空，且actually中的元素类型为Integer。
    assertThat(actually, emptyIterableOf(Integer.class));
}

9）IsMapContaining<K,V>：匹配Map中key、value、entry等相关的匹配器。

@Test
public void testIsMapContaining()
{
    //actually map
    Map<String, String> actually = new HashMap<String, String>()
    {
        {
            put("Alex", "Hello Alex");
            put("Wang", "Hello Wang");
            put("Tina", "Hello Tina");
        }
    };

    //断言匹配actually中存在key为“Alex”、value为“Hello Alex”的Entry。
    assertThat(actually, hasEntry("Alex", "Hello Alex"));
    assertThat(actually, hasEntry(is("Alex"), endsWith("Alex")));

    //断言匹配actually中存在Key为“Wang”的item。
    assertThat(actually, hasKey("Wang"));
    assertThat(actually, hasKey(is(equalTo("Wang"))));

    //断言匹配actually中存在value为“Hello Alex”的item。
    assertThat(actually, hasValue("Hello Alex"));
    assertThat(actually, hasValue(is("Hello Alex")));
}

10）IsIn<T>：用于匹配某元素存在于数组（Array）、collection或可变长数组中的对象匹配器。

@Test
public void testIsIn()
{
    //断言匹配ArrayList中存在元素1，但是这种写法已被标注为过期，请使用下面的写法。
    assertThat(1, isIn(Arrays.asList(1, 2, 3)));

    //等价于上一行代码，但未被标注为过期。
    assertThat(1, is(in(Arrays.asList(1, 2, 3))));

    //断言匹配数组中存在元素1，但是这种写法已被标注为过期，请使用下面的写法。
    assertThat(1, isIn(new Integer[]{1, 2, 3}));
    //等价于上一行代码，但未被标注为过期。
    assertThat(1, is(in(new Integer[]{1, 2, 3})));
    //断言可变长数组中存在元素1。
    assertThat(1, oneOf(1, 2, 3));
}

collection下还有关于Iterable接口的几个匹配器，限于篇幅此处就不再赘述了，大家可以在本书代码com.wangwenjun.cicd.chapter02.HamcrestUsageTest中找到其用法细节。

2.2.4　org.hamcrest.number

number下的对象匹配器主要用于匹配Double、BigDecimal和其他实现了Comparable接口类型的对象。

1）IsCloseTo：用于匹配在某个delta范围之内的Double类型的数字。

@Test
public void testIsCloseTo()
{
    /*
    operand - the expected value of matching doubles
    error - the delta (+/-) within which matches will be allowed
    */
    //1.0为期望的操作数，而0.04是delta值。
    assertThat(1.03, is(closeTo(1.0, 0.04)));
}

2）BigDecimalCloseTo：用于匹配在某个delta范围之内的BigDecimal类型的数字。

@Test
public void testBigDecimalCloseTo()
{
    /**
     * operand - the expected value of matching BigDecimals
     * error - the delta (+/-) within which matches will be allowed
     */
    //1.0为期望的操作数，而0.03是delta值。
    assertThat(new BigDecimal("1.03"),
        is(closeTo(new BigDecimal("1.0"), new BigDecimal("0.03")))
    );
}

3）OrderingComparison<T extends Comparable<T>>：用于匹配实现了Comparable接口的类型。

@Test
public void testOrderingComparison()
{
    //2>1
    assertThat(2, greaterThan(1));
    //1>=1
    assertThat(1, greaterThanOrEqualTo(1));
    //1<2
    assertThat(1, lessThan(2));
    //1<=1
    assertThat(1, lessThanOrEqualTo(1));
    //H的ASCII码<W的ASCII码。
    assertThat("Hello", lessThan("World"));
}

2.2.5　org.hamcrest.text

text下的对象匹配器主要用于判断字符串是否相等，以及是否存在包含关系等，它还提供了可以忽略空格、大小写的功能（需要注意的是，其中很多方法已被标记为过期，下面的代码注释中已添加了说明和替代方案，请大家在阅读时多留意）。

@Test
public void testIsEmptyString()
{
    //字符串为空或null，已标记为过期，请使用下一行代码。
    assertThat((String) null, isEmptyOrNullString());
    //与上一行代码等价，但未标记为过期。
    assertThat((String) null, is(emptyOrNullString()));
    //字符串为空，或者已标记为过期，请使用下一行代码。
    assertThat("", isEmptyString());
    //与上一行代码等价，但未标记为过期。
    assertThat("", is(emptyString()));
}
@Test
public void testIsEqualIgnoringCase()
{
    //忽略大小写匹配字符串。
    assertThat("alex", equalToIgnoringCase("ALEX"));
}

@Test
public void testIsEqualIgnoringWhiteSpace()
{
    //忽略空格、制表符匹配字符串，但是该方法已标记为过期方法。
    assertThat("   my\tfoo  bar ", equalToIgnoringWhiteSpace(" my  foo bar"));
    //与上一行代码等价，但未标记为过期方法。
    assertThat("   my\tfoo  bar ",
        equalToCompressingWhiteSpace(" my  foo bar")
    );
}

@Test
public void testStringContainsInOrder()
{
    //断言匹配"alexwangwenjun"中的文本顺序："alex"在"jun"之前。
    assertThat("alexwangwenjun",
        stringContainsInOrder(Arrays.asList("alex", "jun"))
    );
}

2.2.6　org.hamcrest.xml

xml下的对象匹配器主要使用xpath表达式，对XML文本的节点、内容和命名空间进行相关的匹配操作（笔者将若干个重载的hasXpath方法测试都写在了同一个单元测试方法中，并且附加了详细的注释说明，在实际工作中，建议大家分开编写单元测试代码，同时应尽量避免单元测试的方法太过复杂，以及包含太多的断言语句）。

@Test
public void testHasXPath() throws Exception
{
    //自定义xml命名空间。
    final NamespaceContext ns = new NamespaceContext()
    {
        public String getNamespaceURI(String prefix)
        {
            return "www.wangwenjun.com/profile";
        }
        public String getPrefix(String namespaceURI)
        {
            return "alex";
        }
        public Iterator getPrefixes(String namespaceURI)
        {
            return Arrays.asList("alex").iterator();
        }
    };
    //定义包含命名空间的xml字符串。
    String actuallyXml = "<?xml version = \"1.0\" encoding = \"UTF-8\"?>" +
            "<alex:contact xmlns:alex = \"www.wangwenjun.com/profile\">" +
            "<alex:name>Wangwenjun</alex:name>" +
            "<alex:age>35</alex:age>" +
            "</alex:contact>";

    //将xml解析为Document。
    Document xmlNode = parse(actuallyXml);
    //断言匹配该文档满足"/contact/age" xpath表达式，即包含age节点。
    assertThat(xmlNode, hasXPath("/contact/age"));
    //断言匹配该文档满足"/contact/age" xpath表达式，即包含age节点，同时位于ns命名空间中。
    assertThat(xmlNode, hasXPath("/contact/age", ns));
    //断言匹配该文档满足"/contact/name"，且name节点的值为"wangwenjun"(忽略大小写)。
    assertThat(xmlNode, hasXPath("/contact/name", is(equalToIgnoringCase("wangwenjun"))));
    //断言匹配该文档满足"/contact/age"，且age节点的值为"35"，同时位于ns命名空间中。
    assertThat(xmlNode, hasXPath("/contact/age", ns, equalTo("35")));
}

//将xml字符串解析为Document对象的方法。
private Document parse(String xml) throws Exception
{
    DocumentBuilderFactory documentBuilderFactory =
            DocumentBuilderFactory.newInstance();
    documentBuilderFactory.setNamespaceAware(false);
    DocumentBuilder documentBuilder =
            documentBuilderFactory.newDocumentBuilder();
            return documentBuilder.parse(
            new ByteArrayInputStream(xml.getBytes()));
}