Test Scenarios

Overview

Test scenarios in the Makers BTG Tests framework are written using Gherkin syntax in Spanish. Feature files define the behavior of the application using a structured, human-readable format that serves as both documentation and executable specifications.

Feature File Structure

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>" 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  |

Location: src/test/resources/features/GeneracionReporte.feature

Gherkin Elements

Language Directive

#language:es

directive

required

Specifies that the feature file uses Spanish language keywords.Syntax: #language:esThis directive must be the first line of the feature file. It tells Cucumber to interpret Gherkin keywords in Spanish (Característica, Dado, Cuando, Entonces, etc.) instead of English.

Without the #language:es directive, Cucumber would expect English keywords like Feature, Given, When, Then, causing parsing errors.

Característica (Feature)

Característica

keyword

required

Declares the high-level feature being tested.Syntax: Característica: <feature description>English equivalent: Feature:

The Característica keyword defines the business capability or feature under test. It should be followed by a concise description that explains the feature’s purpose from a business perspective.

Example

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

This declares that the feature focuses on report generation functionality in the Chronos web application.

Esquema del escenario (Scenario Outline)

Esquema del escenario

keyword

required

Defines a parameterized test scenario that runs multiple times with different data.Syntax: Esquema del escenario: <scenario description>English equivalent: Scenario Outline:

A scenario outline allows you to run the same test scenario with multiple sets of data. Variables are defined using angle brackets <variable_name> and values are provided in the Ejemplos (Examples) table.

Example

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

The [Happy Path] prefix in the scenario name is a naming convention to indicate this tests the main success flow. You can use [Unhappy Path] for error scenarios or [Edge Case] for boundary conditions.

Gherkin Step Keywords

Scenarios are composed of steps using Given-When-Then syntax:

Dado (Given)

Dado

step keyword

required

Defines the initial context or preconditions for the scenario.Syntax: Dado <precondition statement>English equivalent: Given

Purpose

Given steps set up the test environment and establish the initial state before any actions are performed.

Example

Dado el usuario ingresa a la web de Chronos

This step establishes that the user has navigated to the Chronos application as a precondition.

Cuando (When)

Cuando

step keyword

required

Defines the action or event that triggers the behavior being tested.Syntax: Cuando <action statement>English equivalent: When

Purpose

When steps represent the user’s actions or system events that cause a change in the application state.

Example with Parameters

Cuando ingrese los datos del reporte "<report>" para la compañia "<company>" segun la fecha "<report_date>"

This step performs the action of entering report data. The values in angle brackets are placeholders that will be replaced with actual values from the Examples table.

Entonces (Then)

Entonces

step keyword

required

Defines the expected outcome or assertion that verifies the behavior.Syntax: Entonces <expected outcome>English equivalent: Then

Purpose

Then steps verify that the system behaves as expected after the When action is performed.

Example

Entonces se genera el reporte "<report>" de manera exitosa

This step asserts that the report was generated successfully.

Parameters and Data Tables

String Parameters

{string}

parameter type

String parameters are enclosed in double quotes in the feature file.In scenario outlines, use angle brackets for variables: "<variable_name>"

Example

Cuando ingrese los datos del reporte "<report>" para la compañia "<company>" segun la fecha "<report_date>"

The step definition receives these as String parameters:

public void ingrese_los_datos_del_reporte_para_la_compañia_segun_la_fecha(
    String reporte, 
    String compania, 
    String fecha
)

Ejemplos (Examples) Table

Ejemplos

keyword

required

Provides test data for scenario outlines in a table format.Syntax:

Ejemplos:
  | column1 | column2 | column3 |
  | value1  | value2  | value3  |

English equivalent: Examples:

Structure

The Examples table consists of:

Header row - Column names that match variable names in the scenario outline
Data rows - Each row represents one test execution with specific values

Example

Ejemplos:
  | report | company    | report_date |
  | 417    | compañia 1 | 2026-02-01  |

report

string

The report ID to be generated. Replaces <report> placeholders in the scenario.

company

string

The company name for the report. Replaces <company> placeholders in the scenario.

report_date

string

The date for the report in YYYY-MM-DD format. Replaces <report_date> placeholders in the scenario.

Multiple Data Rows

You can add multiple rows to run the same scenario with different data:

Ejemplos:
  | report | company    | report_date |
  | 417    | compañia 1 | 2026-02-01  |
  | 418    | compañia 2 | 2026-02-15  |
  | 419    | compañia 3 | 2026-03-01  |

This would execute the scenario three times with different values.

Complete Scenario Execution

How Cucumber Processes This Feature File

When the CucumberRunner executes the feature file:

Parse language directive - Cucumber switches to Spanish keyword interpretation
Read feature description - “Generación de reportes desde la web de Chronos”
Check tags - Only scenarios with @test tag are selected (configured in runner)
Load scenario outline - Read the scenario template with <variable> placeholders
Process Examples table - For each data row:
- Replace <report> with 417
- Replace <company> with compañia 1
- Replace <report_date> with 2026-02-01
Execute steps - Call corresponding step definition methods:
- el_usuario_ingresa_a_la_web_de_chronos()
- ingrese_los_datos_del_reporte_para_la_compañia_segun_la_fecha("417", "compañia 1", "2026-02-01")
- se_genera_el_reporte_de_manera_exitosa("417")
Report results - Generate test reports showing pass/fail status

Writing New Scenarios

Creating a New Feature File

Create a new .feature file in src/test/resources/features/
Start with the language directive: #language:es
Add a Característica: description
Write scenarios using Dado, Cuando, Entonces keywords
Add appropriate tags (e.g., @test)

Example: New Feature File

#language:es
Característica: Validación de reportes generados

  @test @validation
  Esquema del escenario: Verificar contenido del reporte
    Dado el reporte "<report_id>" fue generado previamente
    Cuando el usuario abre el reporte
    Entonces el reporte contiene la compañia "<company_name>"
    Y el reporte contiene la fecha "<report_date>"
    Ejemplos:
      | report_id | company_name | report_date |
      | 417       | compañia 1   | 2026-02-01  |
      | 418       | compañia 2   | 2026-02-15  |

Additional Spanish Keywords

keyword

Equivalent to And in English. Used to add additional steps of the same type.

Pero

keyword

Equivalent to But in English. Used for negative assertions or contrasting conditions.

Escenario

keyword

Equivalent to Scenario in English. Used for single-execution scenarios without examples.

Best Practices

Feature File Writing Guidelines

Use descriptive names - Scenario names should clearly indicate what is being tested
One feature per file - Keep feature files focused on a single business capability
Keep scenarios independent - Each scenario should be executable in isolation
Use meaningful tags - Organize scenarios with tags for easy filtering
Write declaratively - Focus on what, not how (“the user logs in” vs. “the user clicks the login button”)
Limit step count - Keep scenarios between 3-7 steps for readability
Use examples judiciously - Include boundary values and representative samples
Maintain consistency - Follow the same phrasing patterns across scenarios

Common Anti-Patterns to Avoid

❌ Overly technical steps - Avoid UI implementation details in feature files❌ Too many examples - Don’t use scenario outlines as data-driven tests with hundreds of rows❌ Missing tags - Always tag scenarios appropriately for filtering❌ Duplicate scenarios - Use scenario outlines instead of copying similar scenarios❌ Hard-coded values - Use examples tables for data that might change

CucumberRunner - Configures which feature files to execute
Step Definitions - Implements the Java code for each Gherkin step

Feature File Location

src/test/resources/features/GeneracionReporte.feature

All feature files must be placed in the features directory to be discovered by the CucumberRunner via the @SelectClasspathResource("features") annotation.

Core Components

Overview

Feature File Structure

GeneracionReporte.feature

Gherkin Elements

Language Directive

Característica (Feature)

Example

Tags

Purpose

Usage Examples

Esquema del escenario (Scenario Outline)

Example

Gherkin Step Keywords

Dado (Given)

Purpose

Example

Cuando (When)

Purpose

Example with Parameters

Entonces (Then)

Purpose

Example

Parameters and Data Tables

String Parameters

Example

Ejemplos (Examples) Table

Structure

Example

Multiple Data Rows

Complete Scenario Execution

Writing New Scenarios

Creating a New Feature File

Example: New Feature File

Additional Spanish Keywords

Best Practices

Feature File Location

Build docs developers (and LLMs) love

Core Components

​Overview

​Feature File Structure

​GeneracionReporte.feature

​Gherkin Elements

​Language Directive

​Característica (Feature)

​Example

​Tags

​Purpose

​Usage Examples

​Esquema del escenario (Scenario Outline)

​Example

​Gherkin Step Keywords

​Dado (Given)

​Purpose

​Example

​Cuando (When)

​Purpose

​Example with Parameters

​Entonces (Then)

​Purpose

​Example

​Parameters and Data Tables

​String Parameters

​Example

​Ejemplos (Examples) Table

​Structure

​Example

​Multiple Data Rows

​Complete Scenario Execution

​Writing New Scenarios

​Creating a New Feature File

​Example: New Feature File

​Additional Spanish Keywords

​Best Practices

​Related Documentation

​Feature File Location

Build docs developers (and LLMs) love

Overview

Feature File Structure

GeneracionReporte.feature

Gherkin Elements

Language Directive

Característica (Feature)

Example

Tags

Purpose

Usage Examples

Esquema del escenario (Scenario Outline)

Example

Gherkin Step Keywords

Dado (Given)

Purpose

Example

Cuando (When)

Purpose

Example with Parameters

Entonces (Then)

Purpose

Example

Parameters and Data Tables

String Parameters

Example

Ejemplos (Examples) Table

Structure

Example

Multiple Data Rows

Complete Scenario Execution

Writing New Scenarios

Creating a New Feature File

Example: New Feature File

Additional Spanish Keywords

Best Practices

Related Documentation

Feature File Location