Installation

This guide walks you through setting up a complete development environment for the Makers BTG Tests framework, including Java, Gradle, IDE configuration, and dependency management.

System Requirements

Before you begin, ensure your system meets these requirements:

Component	Minimum Version	Recommended
Java	21 (LTS)	21.0.3 or later
RAM	4 GB	8 GB or more
Disk Space	2 GB	5 GB (including IDE)
Operating System	Windows 10, macOS 10.15, Ubuntu 20.04	Latest stable versions
Chrome Browser	100+	Latest stable

Installing Java 21

Download Java 21

Java 21 is a Long-Term Support (LTS) release required by this framework.

Windows
macOS
Linux (Ubuntu/Debian)

Download from Adoptium:

Select OpenJDK 21 (LTS)
Choose Windows x64
Download the MSI installer
Run the installer and follow the wizard
Ensure “Set JAVA_HOME variable” is checked

Install via Homebrew:

brew install openjdk@21

Link the installation:

sudo ln -sfn /opt/homebrew/opt/openjdk@21/libexec/openjdk.jdk \
  /Library/Java/JavaVirtualMachines/openjdk-21.jdk

sudo apt update
sudo apt install openjdk-21-jdk

Verify Java Installation

Open a new terminal and verify the installation:

java -version

Expected output:

openjdk version "21.0.3" 2024-04-16 LTS
OpenJDK Runtime Environment Temurin-21.0.3+9 (build 21.0.3+9-LTS)
OpenJDK 64-Bit Server VM Temurin-21.0.3+9 (build 21.0.3+9-LTS, mixed mode)

Also verify the Java compiler:

javac -version

Expected output:

javac 21.0.3

If the version shows Java 8, 11, or 17, check your JAVA_HOME environment variable and ensure Java 21 is in your system PATH.

Configure JAVA_HOME (if needed)

If Java isn’t recognized, set the JAVA_HOME environment variable:

Windows
macOS/Linux

Open System Properties → Environment Variables
Add new system variable:
- Variable name: JAVA_HOME
- Variable value: C:\Program Files\Eclipse Adoptium\jdk-21.x.x
Edit Path variable and add: %JAVA_HOME%\bin
Open a new terminal to test

Add to ~/.bashrc, ~/.zshrc, or ~/.bash_profile:

export JAVA_HOME=$(/usr/libexec/java_home -v 21)
export PATH=$JAVA_HOME/bin:$PATH

Apply changes:

source ~/.zshrc  # or ~/.bashrc

Gradle Setup

The Makers BTG Tests project includes Gradle Wrapper, so you don’t need to install Gradle separately. The wrapper ensures everyone uses the same Gradle version.

Gradle Wrapper files (gradlew, gradlew.bat, gradle/wrapper/) are included in the repository. These files manage Gradle installation automatically.

Using Gradle Wrapper

# Make wrapper executable (first time only)
chmod +x gradlew

# Run Gradle tasks
./gradlew --version
./gradlew tasks
./gradlew clean test

Always use the wrapper (./gradlew) instead of a system-installed Gradle to ensure consistency across development environments.

Project Dependencies

The framework’s dependencies are managed via Gradle and defined in build.gradle:

build.gradle

plugins {
    id 'java'
    id 'net.serenity-bdd.serenity-gradle-plugin' version '4.0.46'
}

group = 'org.btg.practual'
version = '1.0.0-SNAPSHOT'

java {
    toolchain {
        languageVersion = JavaLanguageVersion.of(21)
    }
}

ext {
    serenityVersion = '4.0.46'
    junitVersion = '5.10.1'
}

dependencies {
    // Serenity BDD Core & Cucumber
    implementation "net.serenity-bdd:serenity-core:${serenityVersion}"
    implementation "net.serenity-bdd:serenity-cucumber:${serenityVersion}"

    // Screenplay Pattern
    implementation "net.serenity-bdd:serenity-screenplay:${serenityVersion}"
    implementation "net.serenity-bdd:serenity-screenplay-webdriver:${serenityVersion}"

    // JUnit 5
    testImplementation "org.junit.jupiter:junit-jupiter-api:${junitVersion}"
    testRuntimeOnly "org.junit.jupiter:junit-jupiter-engine:${junitVersion}"

    // AssertJ for assertions
    testImplementation "org.assertj:assertj-core:3.24.2"

    // Cucumber JUnit Platform Engine
    testImplementation "io.cucumber:cucumber-junit-platform-engine:7.14.0"
}

Key Dependencies

Serenity BDD (4.0.46)

Core framework providing:

Living documentation and rich HTML reports
Screenshot capture and step logging
Requirements coverage tracking
Integration with Cucumber and JUnit

Serenity Screenplay (4.0.46)

Screenplay pattern implementation:

User-centric test design
Tasks, Actions, Questions
WebDriver integration for UI testing

Cucumber (7.14.0)

BDD framework supporting:

Gherkin syntax for feature files
Step definitions in multiple languages (Spanish supported)
Scenario outlines with examples

JUnit 5 (5.10.1)

Modern test engine with:

Platform Suite API for Cucumber integration
Parallel test execution
Flexible test configuration

AssertJ (3.24.2)

Fluent assertion library for:

Readable, chainable assertions
Rich error messages
Type-safe validations

Downloading Dependencies

When you first run Gradle, it automatically downloads all dependencies:

./gradlew build --refresh-dependencies

Dependencies are cached in:

Linux/macOS: ~/.gradle/caches/
Windows: C:\Users\<username>\.gradle\caches\

The initial download may take 5-10 minutes depending on your internet connection. Subsequent builds will be much faster as dependencies are cached.

IDE Setup

IntelliJ IDEA (Recommended)

IntelliJ IDEA provides excellent support for Java, Gradle, and Cucumber.

Install IntelliJ IDEA

Download from JetBrains:

Community Edition (free) - sufficient for this project
Ultimate Edition (paid) - includes additional features

Install and launch IntelliJ IDEA.

Open the Project

Click Open or File → Open
Navigate to the mkrs-btg-tests directory
Select build.gradle and click Open
Choose Open as Project
IntelliJ will import the Gradle project automatically

Wait for Gradle sync to complete (watch the progress bar at the bottom).

Install Required Plugins

Go to File → Settings → Plugins (or IntelliJ IDEA → Preferences → Plugins on macOS):Install these plugins:

Cucumber for Java - Gherkin syntax highlighting and navigation
Gherkin - Feature file support

Restart IntelliJ after installing plugins.

Configure Project SDK

Go to File → Project Structure → Project
Set SDK to Java 21
Set Language level to “21 - Pattern matching for switch”
Click Apply and OK

Verify Setup

Test the configuration:

Open src/test/java/org/btg/practual/runners/CucumberRunner.java
Right-click in the editor
Select Run ‘CucumberRunner’
Tests should execute and results appear in the Run window

IntelliJ IDEA can navigate between Gherkin steps and their Java implementations. Hold Ctrl (or Cmd on macOS) and click on a step in a .feature file to jump to the step definition.

Visual Studio Code

If you prefer VS Code:

Install Extensions

Install these extensions from the VS Code marketplace:

Extension Pack for Java (Microsoft)
Cucumber (Gherkin) Full Support
Gradle for Java

Open the Project

cd mkrs-btg-tests
code .

VS Code will detect the Gradle project and Java files automatically.

Configure Java Home

Add to .vscode/settings.json:

{
  "java.configuration.runtimes": [
    {
      "name": "JavaSE-21",
      "path": "/path/to/java-21",
      "default": true
    }
  ]
}

Environment Verification

Verify your complete setup:

Check Java and Gradle

java -version
./gradlew --version

Both should show Java 21 and Gradle 8.x.

Build the Project

./gradlew clean build

Expected output:

BUILD SUCCESSFUL in 30s

Run Tests

./gradlew test aggregate

Tests should execute and generate a report in target/site/serenity/index.html.

Verify Report Generation

Open the Serenity report:

open target/site/serenity/index.html

You should see test results, requirements, and execution details.

If all steps complete successfully, your environment is ready for test development!

Chrome Browser Setup

The framework uses Chrome for UI testing with automatic driver management.

Install Chrome

Windows
macOS
Linux

Download from google.com/chrome and install.

brew install --cask google-chrome

wget https://dl.google.com/linux/direct/google-chrome-stable_current_amd64.deb
sudo dpkg -i google-chrome-stable_current_amd64.deb
sudo apt-get install -f

Selenium Manager

The framework uses Selenium Manager for automatic ChromeDriver management. No manual driver download is needed! Configuration in serenity.conf:

webdriver {
  driver = chrome
  autodownload = true  # Enables Selenium Manager
}

Selenium Manager automatically downloads and manages the correct ChromeDriver version for your Chrome browser. This eliminates version mismatch issues.

Next Steps

Your development environment is now ready! Continue with:

Quickstart Guide

Run your first test and explore the framework

Writing Tests

Learn how to create new test scenarios

Project Structure

Understand the codebase organization

Configuration

Customize the framework for your needs

Troubleshooting

Gradle sync fails in IntelliJ

Go to File → Invalidate Caches → Invalidate and Restart
Delete .gradle and .idea folders from the project
Re-import the project by opening build.gradle

Wrong Java version is used

Set JAVA_HOME explicitly:

export JAVA_HOME=/path/to/java-21

Or configure in IntelliJ: File → Project Structure → SDKs

Dependencies fail to download

Check internet connection
Clear Gradle cache: rm -rf ~/.gradle/caches/
Retry with: ./gradlew build --refresh-dependencies
If behind a proxy, configure in ~/.gradle/gradle.properties

Chrome not found during tests

Ensure Chrome is installed and in your system PATH. For Linux headless environments, install Chrome or configure for remote execution.

Permission denied: ./gradlew

Make the wrapper executable:

chmod +x gradlew

Get Started

Framework Guide

Writing Tests

Configuration

Running Tests

Best Practices

System Requirements

Installing Java 21

Gradle Setup

Using Gradle Wrapper

Project Dependencies

Key Dependencies

Downloading Dependencies

IDE Setup

IntelliJ IDEA (Recommended)

Visual Studio Code

Environment Verification

Chrome Browser Setup

Install Chrome

Selenium Manager

Next Steps

Quickstart Guide

Writing Tests

Project Structure

Configuration

Troubleshooting

Build docs developers (and LLMs) love

Get Started

Framework Guide

Writing Tests

Configuration

Running Tests

Best Practices

​System Requirements

​Installing Java 21

​Gradle Setup

​Using Gradle Wrapper

​Project Dependencies

​Key Dependencies

​Downloading Dependencies

​IDE Setup

​IntelliJ IDEA (Recommended)

​Visual Studio Code

​Environment Verification

​Chrome Browser Setup

​Install Chrome

​Selenium Manager

​Next Steps

Quickstart Guide

Writing Tests

Project Structure

Configuration

​Troubleshooting

Build docs developers (and LLMs) love

System Requirements

Installing Java 21

Gradle Setup

Using Gradle Wrapper

Project Dependencies

Key Dependencies

Downloading Dependencies

IDE Setup

IntelliJ IDEA (Recommended)

Visual Studio Code

Environment Verification

Chrome Browser Setup

Install Chrome

Selenium Manager

Next Steps

Troubleshooting