---
id: execute_serenity_api_tests
title: Running API tests with Serenity
linkTitle: REST API testing with Serenity
weight: 2
keywords:
  - java
  - rest 
  - api
  - serenity
  - serenity bdd
  - rest assured
  - run serenity tests
  - serenity test example
  - test runner
  - serenity test report
  - execute parallel tests
  - framework
  - testing
  - test
---

link:https://serenity-bdd.github.io/theserenitybook/latest/index.html[Serenity BDD] is an open-source library that aims to make the idea of living documentation a reality. It also uses the test results to produce illustrated, narrative reports that document and describe what your application does and how it works.

== Getting Started

This page explains how to set up the API testing framework built with Java and Serenity BDD.

=== Prerequisites

Set an environment variable `BASE_URL` (e.g. if testing locally, set it to `http://localhost:9000`) or use the `export BASE_URL=http://localhost:9000` command.

== Running the tests

To run all tests, please navigate to the `./api-tests` path and execute the following command:

.Unix
----
./mvnw clean verify
----

.Windows
----
mvnw.cmd clean verify
----

To run the Smoke tests independently, use:

.Unix
----
./mvnw clean verify -Dcucumber.options="--tags @Smoke"
----

.Windows
----
mvnw.cmd clean verify -Dcucumber.options="--tags @Smoke"
----

To run the Functional tests independently, use:

.Unix
----
./mvnw clean verify -Dcucumber.options="--tags @Functional"
----

.Windows
----
mvnw.cmd clean verify -Dcucumber.options="--tags @Functional"
----

To run tests by other tags and ignore tests that contain @Ignore tags, use:

.Unix
----
./mvnw clean verify -Dcucumber.options="--tags ~@Ignore --tags @YourTag"
----

.Windows
----
mvnw.cmd clean verify -Dcucumber.options="--tags ~@Ignore --tags @YourTag"
----

=== Test Report

As a result of the test execution, the `serenity-maven-plugin` will automatically generate the test report at `./api-tests/target/site/serenity/index.html`.

==== Note

To manually aggregate the Serenity report, execute the following command under `./api-tests` directory:

.Unix
----
./mvnw serenity:aggregate
----

.Windows
----
mvnw.cmd serenity:aggregate
----
