Troubleshooting

Common Issues

This guide addresses the most frequently encountered issues when working with the Makers BTG Tests framework. Each section provides diagnostic steps and proven solutions.

Before troubleshooting, ensure you’re using Java 21 and have the latest dependencies from build.gradle.

WebDriver and Browser Issues

Chrome browser not starting

Symptoms:

Error: SessionNotCreatedException: Could not start a new session
Chrome process fails to launch
Timeout waiting for browser

Solutions:

Verify Chrome Installation
```
google-chrome --version
```
Ensure Chrome is installed and accessible.
Update ChromeDriver via Selenium Manager Serenity 4.0.46 uses Selenium Manager which handles driver management automatically. If issues persist:
```
# Clear Selenium cache
rm -rf ~/.cache/selenium
```
Selenium Manager will re-download the correct driver on next run.
Check for Port Conflicts
```
# Check if default debugging port is in use
lsof -i :9222
```
If port is occupied, kill the process or configure a different port in your WebDriver setup.
Run in Headless Mode (for CI/CD) Add to serenity.properties:
```
chrome.switches=--headless,--disable-gpu,--no-sandbox
```

WebDriver version mismatch

Symptoms:

Error: SessionNotCreatedException: This version of ChromeDriver only supports Chrome version X
Browser opens but fails to connect

Solutions:

Let Selenium Manager Handle It The framework uses Selenium Manager (built into Selenium 4.6+) which automatically downloads the correct driver version.
With Serenity 4.0.46 and Selenium Manager, manual WebDriver management is unnecessary.

Update Chrome Browser

# Ubuntu/Debian
sudo apt update && sudo apt upgrade google-chrome-stable

# macOS
brew update && brew upgrade --cask google-chrome

Force Selenium Manager Refresh

rm -rf ~/.cache/selenium
./gradlew clean test

ElementNotInteractableException

Symptoms:

Error: ElementNotInteractableException: element not interactable
Element is present but cannot be clicked

Solutions:

Wait for Element to be Clickable

WebDriverWait wait = new WebDriverWait(driver, Duration.ofSeconds(10));
wait.until(ExpectedConditions.elementToBeClickable(element));
element.click();

Scroll Element into View

((JavascriptExecutor) driver).executeScript(
    "arguments[0].scrollIntoView(true);", element
);
Thread.sleep(500); // Allow scroll animation
element.click();

Check for Overlaying Elements Overlays, modals, or loading spinners may block interaction. Wait for them to disappear:
```
wait.until(ExpectedConditions.invisibilityOfElementLocated(
    By.className("loading-spinner")
));
```

Test Execution Issues

Step definition not found

Symptoms:

Error: Undefined. Implement missing steps
Cucumber cannot match Gherkin steps to Java methods

Solutions:

Verify Glue Path Configuration In CucumberRunner.java:

@ConfigurationParameter(
    key = GLUE_PROPERTY_NAME, 
    value = "org.btg.practual.stepDefinitions"
)

Ensure this matches your step definition package.

Check Step Definition Annotation Verify the Gherkin text exactly matches the annotation:

// Feature file
Dado el usuario ingresa a la web de Chronos

// Step definition - must match exactly
@Dado("el usuario ingresa a la web de Chronos")
public void el_usuario_ingresa_a_la_web_de_chronos() {

Import Correct Cucumber Annotations

// ✅ Correct - Spanish annotations
import io.cucumber.java.es.Dado;
import io.cucumber.java.es.Cuando;
import io.cucumber.java.es.Entonces;

// ❌ Wrong - English annotations
import io.cucumber.java.en.Given;

Rebuild the Project
```
./gradlew clean build
```

Test not found or not executed

Symptoms:

Tests don’t run when executing ./gradlew test
Gradle reports 0 tests executed

Solutions:

Check Tag Filtering Verify tag configuration in CucumberRunner.java:

@ConfigurationParameter(
    key = FILTER_TAGS_PROPERTY_NAME, 
    value = "@test"
)

Ensure your scenarios have the @test tag:

@test
Esquema del escenario: [Happy Path] Generacion exitosa de reporte

Verify Feature File Location Feature files must be in src/test/resources/features/:

src/test/resources/
└── features/
    └── GeneracionReporte.feature

Check JUnit Configuration In build.gradle, verify:
```
test {
    useJUnitPlatform()
}
```
Run with Verbose Output
```
./gradlew test --info
```
This reveals why tests are being filtered or skipped.

ParameterizedTest not executing with examples

Symptoms:

Esquema del escenario (Scenario Outline) runs 0 times
Examples table data not being used

Solutions:

Verify Examples Table Syntax

Esquema del escenario: [Happy Path] Generacion exitosa de reporte
  Dado el usuario ingresa a la web de Chronos
  Cuando ingrese los datos del reporte "<report>" para la compañia "<company>" segun la fecha "<report_date>"
  Entonces se genera el reporte "<report>" de manera exitosa
  Ejemplos:
    | report | company    | report_date |
    | 417    | compañia 1 | 2026-02-01  |

Note: Use Ejemplos: (Spanish) not Examples:

Check Language Declaration Ensure feature file starts with:
```
#language:es
```
Validate Parameter Names Match Parameter names in <> must match table headers exactly.

Build and Dependency Issues

Gradle build fails

Symptoms:

Error: Could not resolve dependencies
Build fails with compilation errors

Solutions:

Clean and Rebuild

./gradlew clean build --refresh-dependencies

Check Java Version

java -version

Must be Java 21 (as specified in build.gradle):

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

Verify Gradle Wrapper

./gradlew --version

If issues persist, regenerate wrapper:

gradle wrapper --gradle-version 8.5

Clear Gradle Cache

rm -rf ~/.gradle/caches
./gradlew clean build

Java version mismatch

Symptoms:

Error: Unsupported class file major version
Error: java.lang.UnsupportedClassVersionError

Solutions:

Install Java 21

# Ubuntu/Debian
sudo apt install openjdk-21-jdk

# macOS (using Homebrew)
brew install openjdk@21

Set JAVA_HOME

# Linux/macOS
export JAVA_HOME=/usr/lib/jvm/java-21-openjdk
export PATH=$JAVA_HOME/bin:$PATH

# Verify
echo $JAVA_HOME
java -version

Use Gradle Toolchain The build.gradle is configured to use Java 21 toolchain, which Gradle will automatically download if needed:
```
java {
    toolchain {
        languageVersion = JavaLanguageVersion.of(21)
    }
}
```

Dependency conflicts

Symptoms:

Error: NoSuchMethodError or ClassNotFoundException
Tests fail with unexpected errors after dependency updates

Solutions:

Review Dependency Tree
```
./gradlew dependencies --configuration testRuntimeClasspath
```
Look for conflicting versions of the same library.

Use Serenity BOM Ensure consistent Serenity versions:

ext {
    serenityVersion = '4.0.46'
}

dependencies {
    implementation "net.serenity-bdd:serenity-core:${serenityVersion}"
    implementation "net.serenity-bdd:serenity-cucumber:${serenityVersion}"
    implementation "net.serenity-bdd:serenity-screenplay:${serenityVersion}"
}

Force Dependency Version If a transitive dependency causes issues:

configurations.all {
    resolutionStrategy {
        force 'org.seleniumhq.selenium:selenium-java:4.15.0'
    }
}

Serenity Report Issues

Serenity reports not generating

Symptoms:

No target/site/serenity directory after test execution
Reports are empty or incomplete

Solutions:

Verify Serenity Plugin Configuration In build.gradle:

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

serenity {
    testRoot = "org.btg.practual"
    requirementsBaseDir = "src/test/resources/features"
    reports = ["html"]
}

Ensure aggregate Task Runs In build.gradle:

test.finalizedBy(aggregate)

Or run manually:

./gradlew test aggregate

Check for Test Execution Reports only generate if tests actually run. Verify tests executed:
```
./gradlew test --info
```

Verify Serenity Reporter Plugin In CucumberRunner.java:

@ConfigurationParameter(
    key = PLUGIN_PROPERTY_NAME,
    value = "io.cucumber.core.plugin.SerenityReporterParallel,pretty,html:target/cucumber-report.html"
)

Reports show 'No requirements' or empty feature list

Symptoms:

Serenity reports generate but show no features or requirements
Test results are not associated with features

Solutions:

Configure Requirements Base Directory In build.gradle:

serenity {
    requirementsBaseDir = "src/test/resources/features"
}

Verify Feature File Structure Feature files must have proper structure:

#language:es
Característica: Generación de reportes desde la web de Chronos

  @test
  Esquema del escenario: [Happy Path] Generacion exitosa de reporte

Check testRoot Configuration In build.gradle:

test {
    systemProperty "serenity.test.root", "org.btg.practual"
}

serenity {
    testRoot = "org.btg.practual"
}

Getting More Help

Serenity BDD Documentation

Official Serenity BDD documentation and guides

Cucumber Documentation

Cucumber reference and best practices

Selenium Documentation

WebDriver and browser automation guides

Gradle Documentation

Build configuration and troubleshooting

When asking for help, always include:

Full error message and stack trace
Java version (java -version)
Gradle version (./gradlew --version)
Relevant code snippets (feature file, step definition, runner)

Get Started

Framework Guide

Writing Tests

Configuration

Running Tests

Best Practices

Common Issues

WebDriver and Browser Issues

Test Execution Issues

Build and Dependency Issues

Serenity Report Issues

Getting More Help

Serenity BDD Documentation

Cucumber Documentation

Selenium Documentation

Gradle Documentation

Build docs developers (and LLMs) love

Get Started

Framework Guide

Writing Tests

Configuration

Running Tests

Best Practices

​Common Issues

​WebDriver and Browser Issues

​Test Execution Issues

​Build and Dependency Issues

​Serenity Report Issues

​Getting More Help

Serenity BDD Documentation

Cucumber Documentation

Selenium Documentation

Gradle Documentation

Build docs developers (and LLMs) love

Common Issues

WebDriver and Browser Issues

Test Execution Issues

Build and Dependency Issues

Serenity Report Issues

Getting More Help