Project Structure - Makers BTG Tests

Overview

The Makers BTG Tests framework follows a standard Maven/Gradle project structure with clear separation between production code, test code, and resources.

This structure follows Java and Gradle conventions, making it familiar to developers and compatible with most IDEs.

Directory Layout

makers-btg-tests/
├── gradle/                      # Gradle wrapper files
│   └── wrapper/
│       ├── gradle-wrapper.jar
│       └── gradle-wrapper.properties
├── src/
│   ├── main/                    # Production code
│   │   └── java/
│   │       └── org/btg/practual/
│   │           └── Main.java
│   └── test/                    # Test code and resources
│       ├── java/
│       │   └── org/btg/practual/
│       │       ├── runners/
│       │       │   └── CucumberRunner.java
│       │       └── stepDefinitions/
│       │           └── GeneracionReporteSteps.java
│       └── resources/
│           ├── features/
│           │   └── GeneracionReporte.feature
│           └── serenity.conf
├── target/                      # Build output (generated)
│   ├── site/serenity/          # Serenity HTML reports
│   ├── cucumber-report.html    # Cucumber HTML report
│   └── test-classes/           # Compiled test classes
├── build.gradle                 # Gradle build configuration
├── gradlew                      # Gradle wrapper script (Unix)
├── gradlew.bat                  # Gradle wrapper script (Windows)
└── settings.gradle              # Gradle settings

Source Directories

src/main/java/

Contains production code (currently minimal):

src/main/java/org/btg/practual/
└── Main.java

The main source directory is reserved for utility classes, helpers, or shared code that’s not test-specific. Most automation code lives in src/test/java/.

src/test/java/

Contains all test automation code:

src/test/java/org/btg/practual/
├── runners/
│   └── CucumberRunner.java          # Test execution entry point
└── stepDefinitions/
    └── GeneracionReporteSteps.java  # Gherkin step implementations

Key Directories Explained

runners/

Purpose: Contains test runner classes that configure and execute tests Location: src/test/java/org/btg/practual/runners/ Example:

@Suite
@IncludeEngines("cucumber")
@SelectClasspathResource("features")
@ConfigurationParameter(key = GLUE_PROPERTY_NAME, value = "org.btg.practual.stepDefinitions")
@ConfigurationParameter(key = FILTER_TAGS_PROPERTY_NAME, value = "@test")
public class CucumberRunner {}

When to add new runners: Create separate runners for different test suites (smoke tests, regression tests, API tests) or when you need different execution configurations.

stepDefinitions/

Purpose: Contains Cucumber step definition classes that link Gherkin steps to Java code Location: src/test/java/org/btg/practual/stepDefinitions/ Current file: GeneracionReporteSteps.java

public class GeneracionReporteSteps {
    
    @Dado("el usuario ingresa a la web de Chronos")
    public void el_usuario_ingresa_a_la_web_de_chronos() {
        System.out.println("Step: el usuario ingresa a la web de Chronos");
    }
    
    // Additional step definitions...
}

Step Definition Best Practices

One class per feature: Create LoginSteps.java, ReportGenerationSteps.java, etc.
Descriptive names: Use names that clearly indicate which feature they support
Shared steps: Common steps (login, navigation) can be in a CommonSteps.java file
Spanish annotations: This project uses Spanish Gherkin keywords (@Dado, @Cuando, @Entonces)

features/

Purpose: Contains Cucumber feature files written in Gherkin syntax Location: src/test/resources/features/ Current file: GeneracionReporte.feature

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

  @test
  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>"
    Entonces se genera el reporte "<report>" de manera exitosa

Feature Organization

Group related scenarios in the same feature fileExamples:

Login.feature
ReportGeneration.feature
UserManagement.feature

Subdirectories

Create subdirectories for large projects:

features/authentication/
features/reports/
features/admin/

Configuration Files

build.gradle

Purpose: Defines project dependencies, plugins, and build tasks Location: Project root Key sections:

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

dependencies {
    implementation "net.serenity-bdd:serenity-core:4.0.46"
    implementation "net.serenity-bdd:serenity-cucumber:4.0.46"
    implementation "net.serenity-bdd:serenity-screenplay:4.0.46"
    implementation "net.serenity-bdd:serenity-screenplay-webdriver:4.0.46"
}

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

Modify build.gradle when:

Adding new dependencies (e.g., REST Assured for API testing)
Updating Serenity or other library versions
Configuring new Gradle tasks
Changing report generation settings

serenity.conf

Purpose: Runtime configuration for Serenity BDD and WebDriver Location: src/test/resources/serenity.conf Key sections:

webdriver {
  driver = chrome
  autodownload = true
  capabilities {
    browserName = "chrome"
    "goog:chromeOptions" {
      args = ["start-maximized", "incognito"]
    }
  }
}

serenity {
    take.screenshots = FOR_FAILURES
    test.root = "org.btg.practual"
    logging = QUIET
}

environments {
  qa {
    webdriver.base.url = "https://qa.btgpactual.com"
  }
  stg {
    webdriver.base.url = "https://stg.btgpactual.com"
  }
}

Use serenity.conf for environment-specific settings like URLs, timeouts, and browser configurations. Avoid hardcoding these values in test code.

Build Output (target/)

Generated during test execution (not committed to version control):

target/
├── site/serenity/               # Serenity HTML reports
│   ├── index.html              # Main report entry point
│   ├── requirements.html       # Requirements coverage
│   ├── capabilities.html       # Test capabilities
│   └── css/                    # Report styling
├── cucumber-report.html         # Cucumber HTML report
├── test-classes/                # Compiled test classes
└── surefire-reports/            # JUnit XML reports

Always add target/ to .gitignore to avoid committing build artifacts to version control.

Adding New Files

Adding a New Feature File

Create the file in src/test/resources/features/
Use the .feature extension
Start with #language:es for Spanish Gherkin
Add feature description and scenarios with appropriate tags

Example:

# Create new feature
touch src/test/resources/features/Login.feature

Adding New Step Definitions

Create a new class in src/test/java/org/btg/practual/stepDefinitions/
Use a descriptive name ending with Steps.java
Import Cucumber annotations: io.cucumber.java.es.*
Implement step methods with @Dado, @Cuando, @Entonces annotations

Example:

# Create new step definitions
touch src/test/java/org/btg/practual/stepDefinitions/LoginSteps.java

Adding Screenplay Components

As you implement the Screenplay pattern, organize code in these directories:

src/test/java/org/btg/practual/
├── tasks/              # High-level business actions
│   ├── Login.java
│   ├── NavigateToChronos.java
│   └── GenerateReport.java
├── interactions/       # Custom low-level interactions
│   └── WaitForPageLoad.java
├── questions/          # Assertions and queries
│   ├── ReportGenerationStatus.java
│   └── TheReportName.java
├── pages/              # Page object targets
│   ├── ChronosHomePage.java
│   └── LoginPage.java
└── abilities/          # Custom actor abilities (if needed)
    └── ManageReports.java

Create these directories as you need them. Start with tasks/ and questions/ first.

Package Structure

All code follows the base package: org.btg.practual Recommended subpackages:

Package	Purpose	Example Classes
`runners`	Test runners	`CucumberRunner`, `SmokeTestRunner`
`stepDefinitions`	Cucumber glue code	`LoginSteps`, `ReportSteps`
`tasks`	Screenplay tasks	`Login`, `GenerateReport`
`questions`	Screenplay questions	`ReportStatus`, `LoginResult`
`pages`	Page object targets	`ChronosHomePage`, `LoginPage`
`models`	Data models	`ReportData`, `UserCredentials`
`utils`	Utilities and helpers	`DateHelper`, `DataGenerator`

Configuration Properties

Gradle Wrapper

Location: gradle/wrapper/gradle-wrapper.properties Purpose: Defines Gradle version for consistent builds

distributionUrl=https\://services.gradle.org/distributions/gradle-8.5-bin.zip

Always use the Gradle wrapper (./gradlew) instead of a locally installed Gradle to ensure consistent builds across environments.

Settings

Location: settings.gradle Purpose: Defines root project name

rootProject.name = 'makers-btg-tests'

Best Practices

Follow Package Conventions

Keep all code under org.btg.practual for consistency

Organize by Feature

Group related feature files, step definitions, and page objects together

Use Descriptive Names

File and class names should clearly indicate their purpose

Keep Tests in src/test/

All test code belongs in src/test/, not src/main/

Version Control

Commit source files, ignore target/ and build outputs

IDE Compatibility

Structure works with IntelliJ, Eclipse, and VS Code

IDE Setup

IntelliJ IDEA

Open project: File > Open > Select build.gradle
IntelliJ auto-detects Gradle and imports dependencies
Mark src/test/java as Test Sources (usually automatic)
Mark src/test/resources as Test Resources
Install Cucumber for Java plugin for feature file support

VS Code

Install extensions:
- Extension Pack for Java
- Cucumber (Gherkin) Full Support
- Gradle for Java
Open project folder
VS Code detects Gradle and configures the project

For more architectural details, see Framework Architecture. To understand Serenity configuration, visit Serenity BDD Integration.

Quick Reference

Task	Command
Run all tests	`./gradlew test`
Run with tag filter	`./gradlew test -Dcucumber.filter.tags="@smoke"`
Run specific environment	`./gradlew test -Denvironment=qa`
Generate reports only	`./gradlew aggregate`
Clean build directory	`./gradlew clean`
View dependencies	`./gradlew dependencies`
Build without tests	`./gradlew build -x test`

Get Started

Framework Guide

Writing Tests

Configuration

Running Tests

Best Practices

​Overview

​Directory Layout

​Source Directories

​src/main/java/

​src/test/java/

​Key Directories Explained

​runners/

​stepDefinitions/

​features/

Feature Organization

Subdirectories

​Configuration Files

​build.gradle

​serenity.conf

​Build Output (target/)

​Adding New Files

​Adding a New Feature File

​Adding New Step Definitions

​Adding Screenplay Components

​Package Structure

​Configuration Properties

​Gradle Wrapper

​Settings

​Best Practices

Follow Package Conventions

Organize by Feature

Use Descriptive Names

Keep Tests in src/test/

Version Control

IDE Compatibility

​IDE Setup

​IntelliJ IDEA

​VS Code

​Quick Reference

Build docs developers (and LLMs) love

Overview

Directory Layout

Source Directories

src/main/java/

src/test/java/

Key Directories Explained

runners/

stepDefinitions/

features/

Configuration Files

build.gradle

serenity.conf

Build Output (target/)

Adding New Files

Adding a New Feature File

Adding New Step Definitions

Adding Screenplay Components

Package Structure

Configuration Properties

Gradle Wrapper

Settings

Best Practices

IDE Setup

IntelliJ IDEA

VS Code

Quick Reference