Tzatziki Steps Library
This project is a collection of ready-to-use Cucumber steps making it easy to TDD Java microservices by focusing on an outside-in testing strategy.
Wait, Cucumber?
You are a Cucumber veteran? ... jump directly to Content of this project
Otherwise, here is what wikipedia says:
Cucumber is a software tool used by computer programmers for testing other software. It runs automated acceptance tests written in a behavior-driven development (BDD) style. Central to the Cucumber BDD approach is its plain language parser called Gherkin. It allows expected software behaviors to be specified in a logical language that customers can understand. As such, Cucumber allows the execution of feature documentation written in business-facing text.
What does it mean to us developers?
Cucumber provides a mapping between humanly readable test files written in a language called Gherkin and their JUnit implementations. You can think about it as a partition that will execute pieces of JUnit code.
Why using Cucumber?
By creating a separation between a test expression and its implementation, the resulting Cucumber test tends to be a bit more readable than its JUnit counterpart. Additionaly, the reusability of each JUnit implementation is really high, and over time only the Gherkin needs to be added to test a new feature.
Okay ... so how does it work?
Getting started with Cucumber in 5 mins
The Cucumber tests are written in .feature files. Most of the IDEs have support for writting, running and debugging cucumber tests. Since deep down they are just JUnit tests, once they are running everything should be the same: code coverage, reporting etc.
The structure of a .feature file is the following:
Feature: the name of your feature
Here you can put some comments describing your feature
Background: some stuff that needs to be done for every scenario
* a system is running
@this-is-a-tag
Scenario: Change a state in the system
As a User I expect to go from A to C if B happens
Given a state A
When B happens
# we can also put comments if things need a bit of explanation
Then C is the new state of the system
Scenario: some other scenario
...
The lines starting with Given, When, Then are called Steps. Additional Steps keywords are And and But (* is also accepted). Those keywords don't really have a functional meaning, they are just there for us to write nice tests. We could start every step with * and the output of the test would be exactly the same. However, you should choose the one fitting the most the intent of the step you are writing. A big part of the idea behind using Gherkin, is that the tests are the specifications of the code, so it should be enough to read them to understand the product they test.
An optional Background section can be added at the beginning. The steps in it will be repeated before any scenario in the file, like a method annotated with @org.junit.Before.
Each Step has an implementation in plain Java that is annotated with a regular expression matching the step.
So for example:
Given that we do something
will have the following implementation:
@Given("that we do something")
public void do_something(){
// do something here
}
Cucumber can extract parameters directly from a step so that:
Given a user named "bob"
can be implemented as:
@Given("a user named \"(.*)\"")
public void a_user_named(String name){
// create a user with that name
}
But it also supports multiline arguments:
Given the following configuration file:
"""
property: value
"""
@Given("the following configuration file:")
public void the_following_configuration_file(String content){
// do something with the file content
}
as well as tables:
Given the following users:
| id | name |
| 1 | bob |
| 2 | alice |
@Given("the following users")
public void the_following_users(List<Map<String, String>> users){
// do something with those users
}
Those Java methods need to be added to a Steps class, typically something like LocalSteps. Keep in mind that for technical reasons Cucumber will not allow you to extend those steps. Instead, the framework will enforce composition, and if any class extending a Steps class is detected, an exception will be thrown.
Cucumber also comes with support for injection frameworks, so all your dependencies will be properly instantiated and injected at runtime, per scenario.
Note that your @org.junit.Before and @org.junit.After annotations won't work in your steps. You need to use the Cucumber equivalent: @cucumber.api.java.Before and @cucumber.api.java.After
Example:
public class BaseSteps {
@Before
public void before() {
// something to run before each scenario
}
@Given("that we do something")
public void do_something(){
// do something here
}
}
public class LocalSteps {
private final BaseSteps baseSteps;
public LocalSteps(BaseSteps baseSteps) {
this.baseSteps = baseSteps;
}
@Given("a user named \"(.*)\"")
public void a_user_named(String name){
baseSteps.do_something();
// create a user with that name
}
@Given("the following users")
public void the_following_users(List<Map<String, String>> users){
// do something with those users
}
@After
public void after() {
// something to run after each scenario
}
}
Finally, in order to have JUnit execute our Cucumber tests we need a runner:
package com.yourcompany.yourproject;
import io.cucumber.junit.Cucumber;
import io.cucumber.junit.CucumberOptions;
import org.junit.runner.RunWith;
@RunWith(Cucumber.class)
@CucumberOptions(plugin = "pretty")
public class CucumberTest {}
By default, cucumber will look for .feature files in the same directory structure than the java runner. However, this can be configured using the features property on the @io.cucumber.junit.CucumberOptions annotation. In addition, it will also look for Java classes containing steps next to the runner and this can also be configured by using the glues property on the same annotation.
Tip: Sometimes it can be hard to come up with the implementation steps... but if you start by typing your new step in your feature file and then execute the scenario, Cucumber will output an implementation for you:
Undefined step: Given something else that is not yet implemented
Skipped step
Skipped step
Skipped step
1 Scenarios (1 undefined)
5 Steps (3 skipped, 1 undefined, 1 passed)
0m0.250s
You can implement missing steps with the snippets below:
@Given("^something else that is not yet implemented")
public void something_else_that_is_not_yet_implemented() throws Throwable {
// Write code here that turns the phrase above into concrete actions
throw new PendingException();
}
Content of this project
This repository contains several libraries, each one having its own tutorial and documentation when applicable:
- tzatziki-common : dependency module containing the base classes for the core library, but without cucumber.
- tzatziki-core : the core library, provides support of our test instances as well as input/output and time management.
- tzatziki-logback : the logging library, provides support for dynamically configuring the log levels in your tests.
- mockfaster : static wrapper around mockserver to reduce the time taken by redefining mocks.
- tzatziki-http : http library encapsulating both rest-assured and mockserver.
- tzatziki-spring : base library to start a spring service
- tzatziki-spring-jpa : support for spring jpa to insert and assert data in the database.
- tzatziki-spring-kafka : support for spring kafka listener and consumers.
Support
We welcome contributions, opinions, bug reports and feature requests!
![[tzatziki-spring] Multiple bean found when launching scenario for a WebFlux application](https://avatars.githubusercontent.com/u/6195718?v=4)
The error : bad SQL grammar [TRUNCATE xxxxx RESTART IDENTITY CASCADE]; nested exception is java.sql.SQLSyntaxErrorException: ORA-03290: Commande de troncation erronée - mot-clé CLUSTER ou TABLE absent
![[tzatziki-http] Invalid regex throwing PatternSyntaxException in callback function for interaction and is not caught](https://avatars.githubusercontent.com/u/107483431?v=4)
![[tzatziki-spring] Spring-Web dependencies are transitive](https://avatars.githubusercontent.com/u/69139631?v=4)
2 Jul 18, 2022
10 Jun 1, 2021
60 Oct 11, 2022
108 Dec 22, 2022
1 Jan 9, 2022
40 Dec 29, 2022
37 Oct 6, 2022
10 Nov 27, 2022
65 Dec 23, 2022
4 Dec 17, 2022
3.5k Jan 5, 2023
98 Jan 7, 2023
2 Nov 28, 2022
5 Dec 27, 2022
1.6k Dec 6, 2022
2 Nov 19, 2017
3 Jan 10, 2022
44 Nov 12, 2022