Hamcrest Object Matchers – 哈姆克雷斯特对象匹配器

1. Overview

1.概述

Hamcrest provides matchers for making unit test assertions simpler and more legible. You can get started exploring some of the available matchers here.

Hamcrest 提供了匹配器，用于使单元测试断言更简单、更清晰。您可以开始探索一些可用的匹配器这里。

In this quick tutorial, we’ll dive deeper into object matchers.

在这个快速教程中，我们将更深入地研究对象匹配器。

2. Setup

2.设置

To get Hamcrest, we just need to add the following Maven dependency to our pom.xml:

要获得Hamcrest，我们只需要在我们的pom.xml中添加以下Maven依赖。

<dependency>
    <groupId>org.hamcrest</groupId>
    <artifactId>java-hamcrest</artifactId>
    <version>2.0.0.0</version>
    <scope>test</scope>
</dependency>

The latest Hamcrest version can be found over on Maven Central.

最新的Hamcrest版本可以在Maven Central上找到。

3. Object Matchers

3.对象匹配器

Object matchers are meant to perform checks over object’s properties.

对象匹配器是为了对对象的属性进行检查。

Before looking into the matchers, we’ll create a couple of beans to make the examples simple to understand.

在研究匹配器之前，我们将创建几个Bean以使例子简单易懂。

Our first object is called Location and has no properties:

我们的第一个对象叫做Location，没有任何属性。

public class Location {}

We’ll name our second bean City and add the following implementation to it:

我们将把第二个Bean命名为City，并为其添加以下实现。

public class City extends Location {
    
    String name;
    String state;

    // standard constructor, getters and setters

    @Override
    public String toString() {
        if (this.name == null && this.state == null) {
            return null;
        }
        StringBuilder sb = new StringBuilder();
        sb.append("[");
        sb.append("Name: ");
        sb.append(this.name);
        sb.append(", ");
        sb.append("State: ");
        sb.append(this.state);
        sb.append("]");
        return sb.toString();
    }
}

Note that City extends Location. We’ll make use of that later. Now, let’s start with the object matchers!

请注意，城市扩展了地点。我们将在后面使用它。现在，让我们从对象匹配器开始吧!

3.1. hasToString

3.1.hasToString

As the name says, the hasToString method verifies that certain object has a toString method that returns a specific String:

正如其名，hasToString方法验证了某些对象有一个toString方法，该方法返回一个特定的String。

@Test
public void givenACity_whenHasToString_thenCorrect() {
    City city = new City("San Francisco", "CA");
    
    assertThat(city, hasToString("[Name: San Francisco, State: CA]"));
}

So, we’re creating a City and verifying that its toString method returns the String that we want. We can take this one step further and instead of checking for equality, check for some other condition:

因此，我们正在创建一个城市，并验证其toString方法是否返回我们想要的String。我们可以更进一步，不检查平等性，而检查其他条件。

@Test
public void givenACity_whenHasToStringEqualToIgnoringCase_thenCorrect() {
    City city = new City("San Francisco", "CA");

    assertThat(city, hasToString(
      equalToIgnoringCase("[NAME: SAN FRANCISCO, STATE: CA]")));
}

As we can see, hasToString is overloaded and can receive both a String or a text matcher as a parameter. So, we can also do things like:

正如我们所看到的，hasToString是重载的，可以接收一个String或一个文本匹配器作为参数。因此，我们也可以做这样的事情。

@Test
public void givenACity_whenHasToStringEmptyOrNullString_thenCorrect() {
    City city = new City(null, null);
    
    assertThat(city, hasToString(emptyOrNullString()));
}

You can find more information on text matchers here. Now let’s move to the next object matcher.

你可以在这里找到更多关于文本匹配器的信息。现在让我们转到下一个对象匹配器。

3.2. typeCompatibleWith

3.2.typeCompatibleWith

This matcher represents an is-a relationship. Here comes our Location superclass into play:

这个匹配器代表了一个is-a关系。我们的Location超类在此发挥作用。

@Test
public void givenACity_whenTypeCompatibleWithLocation_thenCorrect() {
    City city = new City("San Francisco", "CA");

    assertThat(city.getClass(), is(typeCompatibleWith(Location.class)));
}

This is saying that City is-a Location, which is true and this test should pass. Also, if we wanted to test the negative case:

这是说城市是一个地点，这是真的，这个测试应该通过。另外，如果我们想测试否定的情况。

@Test
public void givenACity_whenTypeNotCompatibleWithString_thenCorrect() {
    City city = new City("San Francisco", "CA");

    assertThat(city.getClass(), is(not(typeCompatibleWith(String.class))));
}

Of course, our City class is not a String.

当然，我们的城市类不是一个字符串。

Finally, note that all Java objects should pass the following test:

最后，请注意，所有的Java对象都应该通过以下测试。

@Test
public void givenACity_whenTypeCompatibleWithObject_thenCorrect() {
    City city = new City("San Francisco", "CA");

    assertThat(city.getClass(), is(typeCompatibleWith(Object.class)));
}

Please remember that the matcher is consists of a wrapper over another matcher with the purpose of making the whole assertion more readable.

请记住，匹配器is由另一个匹配器的包装器组成，目的是使整个断言更可读。

4. Conclusion

4.结论

Hamcrest provides a simple and clean way of creating assertions. There is a wide variety of matchers that make every developer’s life simpler as well as every project more readable.

Hamcrest提供了一种创建断言的简单而干净的方法。有各种各样的匹配器，使每个开发人员的生活更简单，也使每个项目更可读。

And object matchers are definitely a straightforward way of checking class properties.

而对象匹配器无疑是检查类属性的一种直接方式。

As always, you’ll find the full implementation over on the GitHub project.

一如既往，你可以在GitHub项目上找到完整的实现。