Getting started

In this quick tutorial, you will learn how to:

  • Write the basic configuration.
  • Write a scenario.
  • Run Wakamiti.
  • Learn the basic workflow.

Please be aware that this tutorial assumes that you have:

  • Some experience using a terminal.
  • Some experience using a text editor.
  • A basic understanding of gherkin syntax.

Before starting, you will need the following:

Optionally:

  • Install an IDE, such as IntelliJ IDEA or VS Code. It's not essential, but it will make scenario development much easier.

0. Start the sample application

Unzip the downloaded zip file containing the tutorial source code, open a terminal in that directory and launch the application with the following command:

docker compose up -d

1. Wakamiti configuration

Wakamiti configuration is created by using a yaml file that will be placed in the same directory where the tests are located (e.g., where the source code of the tutorial is located):

  tutorial
  ├── application-wakamiti.properties
  ├── docker-compose.yml
+ └── wakamiti.yaml

This is the basic configuration to be able to run tests:

wakamiti:
  resourceTypes:
    - gherkin
  launcher:
    modules:
      - mysql:mysql-connector-java:8.0.28
      - es.iti.wakamiti:rest-wakamiti-plugin
      - es.iti.wakamiti:db-wakamiti-plugin
      - es.iti.wakamiti:html-report-wakamiti-plugin
  htmlReport:
    title: Test
  rest:
    baseURL: http://host.docker.internal:9966/petclinic/api
  database:
    connection:
      url: jdbc:mysql://host.docker.internal:3309/petclinic?useUnicode=true
      username: root
      password: petclinic
      driver: com.mysql.cj.jdbc.Driver

NOTE
Note that each plugin has its own configuration, which can be checked in their respective sections. You can also check other options in global configuration.

2. Scenario definition

When we do Behaviour-Driven Development, we specify what we want the software to do using concrete examples. Scenarios are written before production code. They start their life as an executable specification. As the production code emerges, scenarios take on a role as living documentation and automated tests.

A scenario belongs to a specific software feature. Each feature can contain many scenarios, and are defined in .feature files that must be in our working directory (or subdirectory).

A specific example in this tutorial would be to consult a pet owner.

Create an empty file named example.feature with the following content:

Feature: Get the pets owners

  Scenario: An existing owner is consulted
    Given the REST service '/owners/{id}'
    And the path parameter 'id' with value '20'
    And the following user is inserted into the table owners:
      | ID  | FIRST_NAME | LAST_NAME      |
      | 20  | Pepe       | Perez Martínez |
    When the user is requested
    Then the response HTTP code is equal to 200
    And the response is:
      """json
      {
        "id": 20,
        "firstName": "Pepe",
        "lastName": "Perez Martínez"
      }
      """

The first line of this file starts with the keyword Feature: followed by a name. It is recommended to use a similar name to the file name.

The third line, Scenario: An existing owner is queried, is a scenario (i.e., a specific example that illustrates how the software should behave).

The rest of the lines starting with Given, When, Then, And are the steps of our scenario, and are what Wakamiti will execute.

See more in detail the gherkin syntax.

3. Run Wakamiti

Tests are executed with the terminal, from the working directory (the one containing the Wakamiti features and the .feature file we have created), with the following command:

  • Windows:
docker run --rm -v "%cd%:/wakamiti" wakamiti/wakamiti
  • Linux:
docker run --rm -v "$(pwd):/wakamiti" --add-host=host.docker.internal:host-gateway wakamiti/wakamiti

With this command, the latest version of Wakamiti will be downloaded. To work with a specific version, it should be specified in the Docker command as follows: wakamiti/wakamiti:version. The available versions can be checked in the Wakamiti dockerhub repository.

4.Reports

Once the tests are executed, the results are generated in two formats: wakamiti.json and wakamiti.html.

The current states available in Wakamiti are:

  • PASSED: test case is correct, the same result as expected is received from the system.
  • NOT IMPLEMENTED: test case exists, but its steps are not defined.
  • SKIPPED: test case has not been executed.
  • UNDEFINED: there is no such step in Wakamiti.
  • FAILED: there is a check error, it does not match what is expected from what the system returns.
  • ERROR: there is an unexpected error in the system (connection error, database error, time out error...).

Here's the demo!