Introduction to Serenity BDD – 宁静的BDD简介

1. Introduction

1.介绍

In this tutorial, we’ll give an introduction to Serenity BDD – a great tool for applying Behaviour Driven Development (BDD). This is a solution for automated acceptance testing that generates well-illustrated testing reports.

在本教程中，我们将介绍Serenity BDD–应用行为驱动开发（BDD）的一个伟大工具。这是一个用于自动化验收测试的解决方案，可生成图文并茂的测试报告。

2. Core Concepts

2.核心概念

The concepts behind Serenity follow the concepts behind BDD. If you want to read more about it, check our article about Cucumber and JBehave.

Serenity背后的概念遵循BDD背后的概念。如果您想阅读更多相关内容，请查看我们关于Cucumber和JBehave的文章。

2.1. Requirements

2.1.要求

In Serenity, requirements are organized into three levels:

在Serenity，要求被组织成三个层次。

1. capabilities
2. features
3. stories

Typically, a project implements high-level capabilities, e.x. order management and membership management capabilities in an e-commerce project. Each capability is comprised of many features, and features are explained in detail by user stories.

通常情况下，一个项目实现高层次的能力，如电子商务项目中的订单管理和会员管理能力。每个能力都是由许多功能组成的，功能由用户故事详细解释。

2.2. Steps and Tests

2.2.步骤和测试

Steps contain a group of resource manipulation operations. It can be an action, verification or a context related operation. The classic Given_When_Then format can be reflected in the steps.

步骤包含一组资源操作的操作。它可以是一个动作、验证或与上下文相关的操作。经典的Given_When_Then格式可以反映在步骤中。

And tests go hand in hand with Steps. Each test tells a simple user story, which is carried out using certain Step.

而测试与步骤是相辅相成的。 每个测试都讲述了一个简单的用户故事，通过某些步骤来完成。

2.3. Reports

2.3.报告

Serenity not only reports the test results but also uses them for producing living documentation describing the requirements and application behaviors.

Serenity不仅报告测试结果，而且还用它们来制作描述需求和应用行为的活的文档。

3. Testing With SerenityBDD

3.用SerenityBDD测试

To run our Serenity tests with JUnit, we need to @RunWith the SerenityRunner, test runner. SerenityRunner instruments the step libraries and ensures that the test results will be recorded and reported on by the Serenity reporters.

为了用JUnit运行我们的Serenity测试，我们需要@RunWith SerenityRunner，测试运行器。SerenityRunner记录步骤库，确保测试结果将被Serenity报告者记录和报告。

3.1. Maven Dependencies

3.1.Maven的依赖性

To make use of Serenity with JUnit, we should include serenity-core and serenity-junit in the pom.xml:

为了利用JUnit的Serenity，我们应该在pom.xml中包括serenity-core和serenity-junit：

<dependency>
    <groupId>net.serenity-bdd</groupId>
    <artifactId>serenity-core</artifactId>
    <version>1.2.5-rc.11</version>
</dependency>
<dependency>
    <groupId>net.serenity-bdd</groupId>
    <artifactId>serenity-junit</artifactId>
    <version>1.2.5-rc.11</version>
</dependency>

We also need serenity-maven-plugin to have reports aggregated from test results:

我们还需要serenity-maven-plugin，以便从测试结果中汇总出报告。

<plugin>
    <groupId>net.serenity-bdd.maven.plugins</groupId>
    <artifactId>serenity-maven-plugin</artifactId>
    <version>1.2.5-rc.6</version>
    <executions>
        <execution>
            <id>serenity-reports</id>
            <phase>post-integration-test</phase>
            <goals>
                <goal>aggregate</goal>
            </goals>
        </execution>
    </executions>
</plugin>

If we want Serenity to generate reports even if there’s a test failure, add the following to the pom.xml:

如果我们想让Serenity在测试失败时也能生成报告，请在pom.xml中添加以下内容：。

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-surefire-plugin</artifactId>
    <version>2.20</version>
    <configuration>
        <testFailureIgnore>true</testFailureIgnore>
    </configuration>
</plugin>

3.2. A Membership Points Example

3.2.一个会员积分的例子

Initially, our tests are based on the typical membership points feature in an e-commerce application. A customer can join the member program. As the customer purchases goods on the platform, the membership points will increase, and the customer’s membership grade would grow accordingly.

最初，我们的测试是基于电子商务应用中典型的会员积分功能。一个客户可以加入会员计划。随着客户在平台上购买商品，会员积分会增加，客户的会员等级也会相应增长。

Now let’s write several tests against the scenarios described above and see how Serenity works.

现在让我们针对上面描述的场景写几个测试，看看Serenity是如何工作的。

First, let’s write the test for membership initialisation and see which steps do we need:

首先，让我们写一下成员初始化的测试，看看我们需要哪些步骤。

@RunWith(SerenityRunner.class)
public class MemberStatusIntegrationTest {

    @Steps 
    private MemberStatusSteps memberSteps;

    @Test
    public void membersShouldStartWithBronzeStatus() {
        memberSteps.aClientJoinsTheMemberProgram();
        memberSteps.theMemberShouldHaveAStatusOf(Bronze);
    }
}

Then we implement the two steps as follows:

然后，我们实施这两个步骤如下。

public class MemberStatusSteps {

    private Member member;

    @Step("Given a member has {0} points")
    public void aMemberHasPointsOf(int points) {
        member = Member.withInitialPoints(points);
    }

    @Step("Then the member grade should be {0}")
    public void theMemberShouldHaveAStatusOf(MemberGrade grade) {
        assertThat(member.getGrade(), equalTo(grade));
    }
}

Now we are ready to run an integration test with mvn clean verify. The reports will be located at target/site/serenity/index.html:

现在我们准备用mvn clean verify运行一个集成测试。报告将位于target/site/serenity/index.html。

From the report, we can see that we have only one acceptance test ‘Members should start with bronze status, has the ability to’ and is passing. By clicking on the test, the steps is illustrated:

从报告中，我们可以看到，我们只有一个验收测试 “成员应该以青铜状态开始，有能力”，并且正在通过。通过点击测试，说明了测试的步骤。

As we can see, Serenity’s report gives us a thorough understanding of what our application is doing and if it aligns our requirements. If we have some steps to implement, we can mark them as @Pending:

我们可以看到，Serenity的报告让我们彻底了解我们的应用程序正在做什么，是否符合我们的要求。如果我们有一些步骤需要实施，我们可以把它们标记为@Pending。

@Pending
@Step("When the member exchange {}")
public void aMemberExchangeA(Commodity commodity){
    //TODO
}

The report would remind us what needs to be done next. And in case any test fails, it can be seen in the report as well:

该报告会提醒我们接下来需要做什么。而且，万一任何测试失败，也可以在报告中看到。

Each failed, ignored or skipped step will be listed respectively:

每个失败的、被忽略的或跳过的步骤将被分别列出。

4. Integration With JBehave

4.与JBehave的集成

Serenity can also integrate with existing BDD frameworks such as JBehave.

Serenity还可以与现有的BDD框架集成，如JBehave。

4.1. Maven Dependencies

4.1.Maven的依赖性

To integrate with JBehave, one more dependency serenity-jbehave is needed in the POM:

为了与JBehave集成，在POM中还需要一个依赖项serenity-jbehave。

<dependency>
    <groupId>net.serenity-bdd</groupId>
    <artifactId>serenity-jbehave</artifactId>
    <version>1.24.0</version>
</dependency>

4.2. JBehave Github REST API Test Continued

4.2.JBehave Github REST API测试继续进行

As we have introduced how to do REST API testing with JBehave, we can continue with our JBehave REST API test and see how it fits in Serenity.

由于我们已经介绍了如何使用JBehave进行REST API测试，我们可以继续进行我们的JBehave REST API测试，并看看它在Serenity中的表现。

Our story was:

我们的故事是。

Scenario: Github user's profile should have a login payload same as username
 
Given github user profile api
When I look for eugenp via the api
Then github's response contains a 'login' payload same as eugenp

The Given_When_Then steps can be migrated to as @Steps without any changes:

Given_When_Then步骤可以迁移到@Steps而不需要做任何改变。

public class GithubRestUserAPISteps {

    private String api;
    private GitHubUser resource;

    @Step("Given the github REST API for user profile")
    public void withUserProfileAPIEndpoint() {
        api = "https://api.github.com/users/%s";
    }

    @Step("When looking for {0} via the api")
    public void getProfileOfUser(String username) throws IOException {
        HttpResponse httpResponse = getGithubUserProfile(api, username);
        resource = retrieveResourceFromResponse(httpResponse, GitHubUser.class);
    }

    @Step("Then there should be a login field with value {0} in payload of user {0}")
    public void profilePayloadShouldContainLoginValue(String username) {
        assertThat(username, Matchers.is(resource.getLogin()));
    }

}

To make JBehave’s story-to-code mapping work as expected, we need to implement JBehave’s step definition using @Steps:

为了使JBehave的故事到代码的映射如期进行，我们需要使用@Steps实现JBehave的步骤定义。

public class GithubUserProfilePayloadStepDefinitions {

    @Steps
    GithubRestUserAPISteps userAPISteps;

    @Given("github user profile api")
    public void givenGithubUserProfileApi() {
        userAPISteps.withUserProfileAPIEndpoint();
    }

    @When("looking for $user via the api")
    public void whenLookingForProfileOf(String user) throws IOException {
        userAPISteps.getProfileOfUser(user);
    }

    @Then("github's response contains a 'login' payload same as $user")
    public void thenGithubsResponseContainsAloginPayloadSameAs(String user) {
        userAPISteps.profilePayloadShouldContainLoginValue(user);
    }
}

With SerenityStories, we can run JBehave tests both from within our IDE and in the build process:

通过SerenityStories，我们可以在IDE中和构建过程中运行JBehave测试。

import net.serenitybdd.jbehave.SerenityStory;

public class GithubUserProfilePayload extends SerenityStory {}

After the verify build finished, we can see our test report:

在verify构建完成后，我们可以看到我们的测试报告。

Compared to plain text report of JBehave, the rich report by Serenity gives us a more eye-pleasing and live overview of our story and the test result.

与JBehave的纯文本报告相比，Serenity的丰富报告为我们提供了一个更令人赏心悦目的故事和测试结果的实时概述。

5. Integration With REST-assured

5.与REST-保证的集成

It is noteworthy that Serenity supports integration with REST-assured. To have a review of REST-assured, take a look at the guide to REST-assured.

值得注意的是，Serenity支持与REST-assured集成。要对REST-assured进行审查，请看REST-assured的指南.。

5.1. Maven Dependencies

5.1.Maven的依赖性

To make use of REST-assured with Serenity, the serenity-rest-assured dependency should be included:

为了在Serenity中使用REST-assured，应该包括serenity-rest-assured依赖项。

<dependency>
    <groupId>net.serenity-bdd</groupId>
    <artifactId>serenity-rest-assured</artifactId>
    <version>1.2.5-rc.11</version>
</dependency>

5.2. Use REST-assured in Github REST API Test

5.2.在Github REST API测试中使用REST-assured

Now we can replace our web client with REST-assured utilities:

现在我们可以用REST保证的实用程序来取代我们的网络客户端。

import static net.serenitybdd.rest.SerenityRest.rest;
import static net.serenitybdd.rest.SerenityRest.then;

public class GithubRestAssuredUserAPISteps {

    private String api;

    @Step("Given the github REST API for user profile")
    public void withUserProfileAPIEndpoint() {
        api = "https://api.github.com/users/{username}";
    }

    @Step("When looking for {0} via the api")
    public void getProfileOfUser(String username) throws IOException {
        rest().get(api, username);
    }

    @Step("Then there should be a login field with value {0} in payload of user {0}")
    public void profilePayloadShouldContainLoginValue(String username) {
        then().body("login", Matchers.equalTo(username));
    }

}

After replacing the implementation of userAPISteps in the StepDefition, we can re-run the verify build:

在替换了StepDefition中的userAPISteps的实现后，我们可以重新运行verify构建。

public class GithubUserProfilePayloadStepDefinitions {

    @Steps
    GithubRestAssuredUserAPISteps userAPISteps;

    //...

}

In the report, we can see the actual API invoked during the test, and by clicking on the REST Query button, the details of request and response will be presented:

在报告中，我们可以看到测试期间实际调用的API，通过点击REST查询按钮，请求和响应的细节将被呈现出来。

6. Integration With JIRA

6.与JIRA的整合

As of now, we already have a great test report describing details and status of our requirements with Serenity framework. But for an agile team, issue tracking systems such as JIRA are often used to keep track of requirements. It would be better if we could use them seamlessly.

到现在为止，我们已经有了一份很好的测试报告，描述了Serenity框架的细节和需求的状态。但是对于一个敏捷的团队来说，问题跟踪系统，如JIRA，经常被用来跟踪需求。如果我们能无缝地使用它们，那就更好了。

Luckily, Serenity already supports integration with JIRA.

幸运的是，Serenity已经支持与JIRA的整合。

6.1. Maven Dependencies

6.1.Maven的依赖性

To integrate with JIRA, we need another dependency: serenity-jira-requirements-provider.

为了与JIRA集成，我们需要另一个依赖项。serenity-jira-requirements-provider.。

<dependency>
    <groupId>net.serenity-bdd</groupId>
    <artifactId>serenity-jira-requirements-provider</artifactId>
    <version>1.1.3-rc.5</version>
</dependency>

6.2. One-way Integration

6.2.单向整合

To add JIRA links in the story, we can add the JIRA issue using story’s meta tag:

为了在故事中添加JIRA链接，我们可以使用故事的元标签添加JIRA问题。

Meta:
@issue #BDDTEST-1

Besides, JIRA account and links should be specified in the file serenity.properties at the root of the project:

此外，JIRA账户和链接应在项目根部的serenity.properties文件中指定。

jira.url=<jira-url>
jira.project=<jira-project>
jira.username=<jira-username>
jira.password=<jira-password>

Then there would be a JIRA link appended in the report:

然后，报告中会有一个JIRA链接。

Serenity also supports two-way integration with JIRA, we can refer to the official documentation for more details.

Serenity还支持与JIRA的双向集成，我们可以参考官方文档了解更多细节。

7. Summary

7.总结

In this article, we introduced Serenity BDD and multiple integrations with other test frameworks and requirement management systems.

在这篇文章中，我们介绍了Serenity BDD以及与其他测试框架和需求管理系统的多种集成。

Although we have covered most of what Serenity can do, it can certainly do more. In our next article, we’ll cover on how Serenity with WebDriver support can enable us to automate web application pages using screenplay.

尽管我们已经介绍了Serenity能做的大部分事情，但它当然还能做更多。在下一篇文章中，我们将介绍Serenity如何在WebDriver的支持下使我们能够使用screenplay实现Web应用页面的自动化。

As always, the full implementation code can be found over on the GitHub project.

一如既往，完整的实施代码可以在GitHub项目上找到。