In fast-moving development environments, ensuring your application stays stable with every change can be challenging. That’s where automated testing comes in — it’s a crucial tool for catching issues early and keeping your software reliable as it evolves.
As discussed in a previous blog post, Selenium is a popular choice for automation testing, and when you pair it with Cucumber, you unlock even more benefits. By writing test cases in Cucumber’s human-readable format, teams can improve clarity, boost maintainability, and make collaboration easier — even for non-technical stakeholders. In this post, I’ll walk you through how to integrate Cucumber with Selenium to create efficient, effective tests that set your team up for success.
What is Cucumber?
Cucumber is a Behavior-Driven Development (BDD) testing framework that enables writing test cases in plain English using Gherkin, a plain-text language used to define test scenarios. This allows both technical and non-technical stakeholders to understand test scenarios without having to dive into code.
Why Use Cucumber with Selenium?
Combining Selenium and Cucumber can be a game-changer, and I’ve seen it firsthand in the project I’m currently working on at Keyhole. One of the biggest perks is how readable the test scenarios become. Thanks to Cucumber’s Gherkin syntax, writing and understanding test cases feels more like crafting simple instructions rather than wading through complex code.
Another big win is reusability. With step definitions, you can create code components once and use them across multiple test cases — no need to reinvent the wheel each time. On top of that, the clear separation of concerns keeps everything tidy; your business logic remains distinct from test execution, making your tests easier to manage and maintain.
And let’s not forget about CI/CD integration. Cucumber tests slide seamlessly into your pipeline, making continuous testing easier and more efficient. It’s a combination that makes testing not only powerful but also far less painful.
Writing a Cucumber Test
Getting started with Cucumber might seem intimidating at first, but once you break it down, it’s surprisingly straightforward. Every Cucumber test has three key pieces that work together to make it all run smoothly: the Feature File, the Step Definition, and the Test Runner.
- Feature File: This file will contain all of the actual test scenarios written in plain text. The scenario that a user is looking to test is then broken down into the smallest and simplest statements possible. Keywords that start each statement might include THEN, GIVEN, or WHEN.
- Step Definition: This file is where the code for each of the statements is actually written. Here, we define what the plain text statements translate to in terms of code.
- Test Runner: This file is simply the file that kicks off the running of the written tests and contains the locations of both the Step Definition and Feature files. This is the file that brings the whole process together.
Once you’ve got these pieces in place, you’re ready to start building your test. Let’s walk through the steps to set it up using a basic example I came up with.
Step 1: Create a Feature File
Feature files contain test scenarios written in Gherkin. In our basic example, we want the automation to Google search for Keyhole Software, and verify that the Keyhole Software website is visible in the results.
Start by creating a new file, keyholeSearch.feature, under src/test/resources/features/. Add the following content:
Scenario: Verify that the Keyhole Software website is visible on the search results page Given I open the Google homepage Then I search for “Keyhole Software” Then I verify that the Keyhole Software website in the results
Step 2: Implement Step Definitions
The Step file is where we define what the statements written in the feature file will do and write the code needed to get them to execute correctly.
Create a new Java class, GoogleSearchSteps.java, under src/test/java/steps/, and then implement the step definitions, however you see fit. Here’s what the Step file would look like in our example:
import io.cucumber.java.en.Given;
import io.cucumber.java.en.When;
import io.cucumber.java.en.Then;
import org.openqa.selenium.By;
import org.openqa.selenium.WebDriver;
import org.openqa.selenium.chrome.ChromeDriver;
import static org.junit.Assert.assertTrue;
public class GoogleSearchSteps {
WebDriver driver;
@Given("I open the Google homepage")
public void openGoogleHomepage() {
System.setProperty("webdriver.chrome.driver", "path/to/chromedriver");
driver = new ChromeDriver();
driver.get("https://www.google.com");
}
@When("I search for {string}")
public void searchFor(String query) {
driver.findElement(By.name("googleSearchBar")).sendKeys(query);
driver.findElement(By.name("googleSearchBar")).submit();
}
@Then("I verify that the {string} website in the results")
public void verifySearchResults(String websiteName) {
assertTrue(driver.getPageSource().contains(websiteName));
driver.quit();
}
}
Step 3: Create the Test Runner
To execute the test, create a new Java class, TestRunner.java, under src/test/java/runner/. Here’s what ours looks like:
import org.junit.runner.RunWith;
import io.cucumber.junit.Cucumber;
import io.cucumber.junit.CucumberOptions;
@RunWith(Cucumber.class)
@CucumberOptions(features = "src/test/resources/features", glue = "steps") public class TestRunner {
}
Step 4: Run the Test
This last step is simple! Run the TestRunner.java file as a JUnit test. It will execute the feature file, open Google, perform a search, and verify the results.
Conclusion
Using Cucumber with Selenium is a smart way to make your test automation both efficient and easy to understand. By structuring tests in a BDD format, teams can create clear, maintainable tests that everyone — from developers to business stakeholders — can follow. This approach really shines in Agile environments, where fast feedback is key to keeping development moving smoothly. With Selenium handling the automation and Cucumber ensuring clarity, you’ve got a powerful combination that keeps your testing process effective and your team on the same page.
