HTML Reports in Cucumber

What Are HTML Reports?

HTML reports are human-readable web pages generated after Cucumber test execution. They provide a visual summary of automation results in a format that can be opened in any modern browser. Instead of reading long console logs, testers and developers can open an HTML file and review executed features, scenarios, steps, pass and fail status, skipped steps, execution time, and failure details in an organized view.

In simple terms, HTML reports provide a graphical view of Cucumber execution results in a web browser. They are one of the easiest reporting outputs to understand because they follow the same hierarchy as a Cucumber test suite. A feature contains scenarios. A scenario contains steps. Each step has a result. The HTML report presents this flow in a readable form.

HTML reports are especially useful for manual review. A developer may use console output while debugging locally, and a CI server may use JUnit XML for build dashboards, but a tester often wants a browser-based summary that can be opened, scanned, and shared. HTML reports provide that first layer of readable evidence after an automation run.

Why HTML Reports Are Important

After automation execution, different stakeholders need different information. Developers usually want to know which step failed and what error message was thrown. Testers want scenario status, execution summary, and failure context. Managers and leads may want pass percentage, failed count, total execution status, and whether critical scenarios passed. HTML reports bring much of this information into one place.

Without a report, execution may finish but leave the team with little useful information. Someone may know that Maven finished or that a runner completed, but that does not explain which business behaviors were validated. A report turns raw execution into readable feedback. It helps the team move from "tests ran" to "these scenarios passed, these failed, and this is where investigation should start."

HTML reports also help preserve execution evidence. If a regression run is performed before a release, the HTML report can be archived as a build artifact. Later, the team can open the report and see what was executed at that point in time. This is useful for release discussions, defect triage, and automation health review.

Reporting Flow

The reporting flow begins with feature files and a runner class. The runner starts Cucumber execution. Cucumber reads feature files, executes scenarios, runs steps through step definitions, applies hooks, and records execution results. The HTML plugin consumes those results and writes an HTML file to the configured output path. After execution, the report can be opened in a browser.

Feature Files
  -> Runner
  -> Cucumber Execution
  -> HTML Plugin
  -> HTML Report
  -> Open in Browser

This flow is simple, but it is important to understand. The HTML report is not written manually by the tester. It is produced by the configured Cucumber plugin. If the plugin is missing or the path is wrong, the report may not be generated even though tests executed. Report configuration is therefore part of framework setup.

Report Generation

Cucumber generates HTML reports using the html plugin. In a Cucumber JVM project with a runner class, the plugin is commonly configured in @CucumberOptions. The plugin value includes the report type and output path. The output path usually points to the Maven target folder.

@CucumberOptions(
  plugin = {
    "html:target/cucumber-report.html"
  }
)

After execution, Cucumber creates the file at the configured location.

target/cucumber-report.html

The exact configuration can vary depending on whether the framework uses JUnit, TestNG, Maven command-line options, or Cucumber properties. The idea remains the same: enable the HTML plugin and define where the generated report should be written.

Execution Flow

The HTML report is built from the execution flow. Cucumber starts with a feature, runs each scenario, executes each step, records the result, and then writes the report. Passed steps, failed steps, skipped steps, undefined steps, and pending steps can all appear depending on what happened during execution.

Execute Feature
  -> Scenario Executes
  -> Steps Execute
  -> Results Stored
  -> HTML Generated

This means report quality depends on scenario quality. If feature and scenario names are clear, the report is clear. If feature files are vague, technical, or poorly named, the report becomes less useful. Reporting is not only a tool feature; it reflects the quality of the underlying Gherkin.

HTML Report Location

In a typical Maven project, generated reports are stored inside the target directory. This directory is commonly recreated during builds and is intended for generated artifacts. Placing reports in target keeps them separate from source files and avoids accidentally committing generated reports to version control.

Project
  src
  pom.xml
  target
    cucumber-report.html

The target folder is also convenient for CI/CD. Build tools and pipeline jobs can archive files from target after execution. If reports are written to random or source folders, pipelines become harder to configure and developers may accidentally mix generated files with real project source files.

Opening the Report

After execution, the report can be opened directly in a browser. A tester can navigate to the target folder and open cucumber-report.html. In CI/CD, the report may be published as an artifact or exposed through the build server interface. The report should be easy to find after every run.

target
  -> cucumber-report.html
  -> Open in Browser

Opening the report is usually the first step after a failed execution. The tester can review the failed feature, scenario, step, exception, and execution status before deciding whether the problem is a product defect, environment issue, test data problem, or automation issue.

HTML Report Contents

A typical HTML report contains the execution hierarchy. It shows features, scenarios, steps, statuses, and execution time. It may also show failure details when something fails. This hierarchy mirrors the feature file structure, making it natural for Cucumber users to understand.

Feature
  -> Scenario
  -> Steps
  -> Status
  -> Execution Time

The content is most useful when the feature files are business-readable. A scenario named "Successful login with valid credentials" tells the reader exactly what passed. A scenario named "TC_001" does not. Good reports begin with good scenario naming.

Feature Summary

The feature summary shows high-level execution results for a feature. If multiple features are executed, each feature is shown separately. This helps readers quickly identify which business areas passed or failed. For example, Login Feature, Customer Feature, Order Feature, and Payment Feature can each appear as separate report sections.

Feature: Login Feature
Status: Passed

Feature-level grouping is useful in larger projects. If failures are concentrated in one feature, the team can focus investigation on that module. If failures appear across many unrelated features, the issue may be environmental, configuration-related, or caused by a shared framework component.

Scenario Summary

Each scenario has its own execution details. The report can show the scenario name, status, steps, and timing. Scenario-level reporting is important because scenarios represent behavior. When a scenario fails, the team should understand which behavior is broken or which automation flow needs review.

Scenario: Valid Login
Status: Passed
Time: 1.8 Seconds

Scenario names should be meaningful enough to appear in reports without extra explanation. "Valid Login" is understandable. "Verify Functionality" is vague. "Scenario 1" is almost useless outside the person who wrote it. Reporting value depends heavily on scenario naming discipline.

Step Details

Step details show the execution status of each Given, When, Then, And, or But step. This is where Cucumber reports become more helpful than a simple pass/fail count. A failed scenario may have many steps, but the report identifies exactly which step failed and where execution stopped.

Given User opens application - PASSED
When User enters credentials - PASSED
Then Dashboard appears - PASSED

Step-level visibility is useful for debugging. A failed Given step may suggest setup or test data issues. A failed When step may suggest action or API execution issues. A failed Then step usually points to assertion or validation mismatch. The report helps narrow the problem quickly.

Failed Step Display

When a step fails, the HTML report identifies the failed step and displays failure information such as exception or stack trace. This is one of the most important sections for debugging. It tells the team where execution stopped and what error was thrown.

Scenario: Login
  -> When User clicks Login
  -> FAILED
  -> Stack Trace

Failure details should be reviewed before rerunning tests. Many teams rerun immediately without reading the report. That wastes time. The report may show a missing element, assertion mismatch, timeout, invalid response, bad credentials, or environment failure. The first debugging step should be report analysis.

Execution Statistics

HTML reports often include execution statistics such as number of features, number of scenarios, passed count, failed count, skipped count, and overall result. These statistics help the team understand test health quickly. A large failure count may indicate a shared issue. A small failure count may indicate isolated product or test problems.

Features: 5
Scenarios: 42
Passed: 40
Failed: 2
Skipped: 0

Execution statistics are useful for daily automation review, release decisions, and regression summaries. They should not be the only evidence used for quality decisions, but they provide a quick starting point. Always inspect failed scenarios before interpreting the numbers.

Execution Time

HTML reports include timing information for features, scenarios, and sometimes steps. Timing helps identify slow tests and performance changes in the automation suite. If one scenario suddenly becomes much slower, it may point to an application slowdown, environment problem, wait issue, or inefficient test design.

Feature: 2 Minutes
Scenario: 15 Seconds
Step: 500 ms

Execution time matters because automation should provide fast feedback. Long-running scenarios may need to be optimized, split, moved to a different suite, or reviewed for unnecessary setup. Reports make slow areas visible.

Pass, Fail, and Skipped Visualization

HTML reports provide visual indicators for passed, failed, and skipped results. These indicators make reports easier to scan than plain text logs. A tester can quickly see where failures are concentrated and which scenarios were not executed because earlier steps failed or because configuration skipped them.

Passed
Failed
Skipped

Skipped steps should not be ignored. In Cucumber, steps after a failed step are often skipped because scenario execution stops. A report with many skipped steps may actually have one root failure that caused later steps not to run. Read the first failed step before analyzing skipped results.

Scenario Flow in Reports

The HTML report follows the same order as the feature file. It shows the feature, then scenario, then Given, When, Then, and additional steps, followed by status. This makes it easy to connect report output back to the source feature file.

Feature
  -> Scenario
  -> Given
  -> When
  -> Then
  -> Status

This consistency is one reason Cucumber reports are readable. The report is not just a technical log. It is a view of the executable specification that ran. When the Gherkin is clear, the report becomes a useful documentation artifact.

Multiple Features

When a suite runs multiple feature files, the HTML report displays them as separate sections. This helps teams understand module-level results. For example, Login Feature, Customer Feature, Order Feature, and Payment Feature may each have their own group of scenarios.

Login Feature
Customer Feature
Order Feature
Payment Feature

Multiple feature reporting is useful in regression runs. If only Payment Feature fails, the payment team can investigate. If all features fail at the first step, the problem may be application startup, environment configuration, authentication, or shared setup. Reports help distinguish local defects from broad failures.

Plugin Configuration with Multiple Reports

HTML reports are usually generated alongside other report formats. Pretty output helps local console review. JSON supports reporting tools and merging. JUnit XML supports CI/CD dashboards. HTML supports manual review. Generating these together is a practical default for real projects.

@CucumberOptions(
  plugin = {
    "pretty",
    "html:target/cucumber-report.html",
    "json:target/cucumber.json",
    "junit:target/cucumber.xml"
  }
)

One execution can generate multiple formats. This avoids rerunning tests just to produce different reports. Each format has a different audience, so combining them improves overall reporting coverage.

HTML vs Console Output

Console output is useful while tests are running. It gives immediate feedback in the terminal. HTML reports are better after execution because they organize results into a browser-friendly format. Console output may disappear once the terminal is closed unless captured by CI logs. HTML reports can be archived, opened, and shared.

Both are useful. A mature framework should provide readable console output and file-based reports. They support different parts of the testing workflow.

HTML Report in CI/CD

In CI/CD, the HTML report should be published or archived as a build artifact. A typical flow starts with a Git commit, triggers Jenkins or another build server, runs Maven tests, executes Cucumber, generates the HTML report, and archives it. Team members can then open the report from the build page.

Git Commit
  -> Jenkins
  -> Maven Test
  -> Cucumber
  -> HTML Report
  -> Publish Artifact

CI/CD integration should also publish JUnit XML results because build tools understand XML better than HTML. HTML is for human review. JUnit XML is for dashboards and build result parsing. JSON is for integrations and advanced reporting. Use each format for its strength.

Screenshot Support

Built-in HTML reports do not automatically embed screenshots in every setup. Screenshot support usually requires framework code. In UI automation, an After hook can detect failure, capture a screenshot from WebDriver, and attach it to the Cucumber scenario. Depending on the report setup, the attachment may appear in the report or be available through generated artifacts.

Scenario Failed
  -> After Hook
  -> Take Screenshot
  -> Attach
  -> Enhanced Report

Screenshots are useful because UI failures often need visual context. A report may say that a button was not clickable, but a screenshot can show that a modal covered the button, the page did not load, or the browser was on the wrong screen. For API testing, screenshots are not needed, but request and response attachments may play a similar diagnostic role.

HTML Report Limitations

Built-in HTML reports are useful but limited. They generally do not provide rich charts, pie graphs, historical trends, dashboard views, test history, automatic screenshots, environment details, ownership analytics, flaky test tracking, or deep team-level insights. They are intended mainly as execution summaries.

For advanced needs, teams often use Extent Reports, Allure Reports, ReportPortal, custom dashboards, or CI analytics. These tools can provide screenshots, charts, categories, retries, trends, and environment metadata. Built-in HTML reports are a good starting point, but large teams may adopt advanced reporting as the framework matures.

Common Mistakes

One common mistake is generating only HTML reports. Enterprise projects usually generate HTML, JSON, and XML together. HTML is readable, JSON is useful for tools, and JUnit XML is useful for CI/CD. Another mistake is overwriting previous reports without archiving them in CI. This makes it harder to investigate older failures.

Storing reports in source folders is also a mistake. Generated artifacts belong in build output directories such as target. Teams also sometimes expect screenshots to appear automatically, but screenshots require explicit capture and attachment logic. Another common mistake is ignoring failed step details and immediately rerunning tests. Always review the report first.

Best Practices

Generate HTML reports for every execution. Store reports in the target directory. Generate JSON and JUnit XML alongside HTML. Archive HTML reports in CI/CD pipelines. Capture screenshots on failures using hooks when UI automation is involved. Review failed steps before rerunning tests. Use HTML reports for manual review and stakeholder communication.

Use advanced reporting tools when richer dashboards, screenshots, historical trends, or analytics are required. Keep report paths consistent. Clean old reports before new local executions when appropriate. Preserve reports from important CI builds. Use meaningful feature and scenario names so reports are easy to understand.

Enterprise Reporting Architecture

In enterprise frameworks, HTML reports are one piece of the reporting architecture. Feature files are executed by a runner. Cucumber runs the scenarios. The HTML plugin creates a browser-readable report. JSON and XML plugins may also produce machine-readable outputs. The HTML report is opened by testers, developers, or leads, while CI tools consume XML and advanced tools may consume JSON.

Feature File
  -> Runner
  -> Cucumber
  -> HTML Plugin
  -> HTML Report
  -> Browser
  -> Tester
  -> Developer
  -> Manager

This makes HTML reports a common execution summary for multiple stakeholders. They are not always the richest reporting option, but they are simple, accessible, and useful.

HTML Report vs JSON Report

HTML reports and JSON reports serve different purposes. HTML is human-readable and viewed in a browser. JSON is machine-readable and used by tools, integrations, dashboards, and report generators. A tester may open HTML directly. A reporting tool may parse JSON and create a richer dashboard.

A good framework often generates both. HTML gives immediate human visibility. JSON preserves structured execution data for future processing.

HTML Report vs Extent Report

Built-in HTML reports are generated by Cucumber and require minimal setup. Extent Reports is a third-party reporting library that supports richer dashboards, screenshot embedding, custom views, categories, and more visual customization. Built-in HTML is good for learning, small projects, and basic summaries. Extent is commonly used in larger enterprise frameworks.

Choose based on project need. Do not add advanced reporting only for appearance. Add it when the team needs richer debugging, visual evidence, historical review, or stakeholder dashboards.

HTML Report Archiving

Archiving HTML reports is important in CI/CD. If a build fails and the report is not archived, the team may lose useful failure details. CI jobs should preserve HTML reports, JSON files, XML files, screenshots, and relevant logs. Each archived report should be tied to a build number, branch, commit, and execution timestamp.

Archived reports also help identify trends manually. If execution time increases over several builds or the same scenario fails repeatedly, archived reports provide evidence. Built-in HTML reports do not provide automatic trend charts, but preserved reports still support investigation.

HTML Report Naming Strategy

Report naming should be predictable. A small project can use target/cucumber-report.html. Larger projects may generate separate files for smoke, regression, API, UI, or module-specific suites. The key is consistency. Developers and CI jobs should know where reports are written.

Avoid constantly changing report paths. If the pipeline expects one file but the runner writes another, reports will not publish. If parallel execution is used, each thread or runner may need a unique report file to avoid overwriting. The CI job can then archive all matching reports.

Using HTML Reports for Debugging

HTML reports should be the first stop after a failed run. Review the failed feature, scenario, step, and error message. Check whether previous steps passed. Look at skipped steps. If screenshots or attachments are available, inspect them. This process often reveals whether the failure is due to application behavior, automation code, data setup, environment availability, or timing.

Rerunning without reading the report may hide useful information. A test may pass on rerun because of timing, but the original failure still indicates instability. Reports help identify these patterns. Good teams use reports to improve both product quality and automation reliability.

Keeping HTML Reports Useful

HTML reports remain useful only when the automation suite is written clearly. Feature names should represent business areas. Scenario names should describe behavior. Steps should be readable. Assertion messages should explain actual mismatches. Tags should identify suites, modules, and risk levels. Without these practices, the report may be technically generated but hard to understand.

Review reports periodically as part of framework maintenance. If failures are hard to analyze, improve step names, assertion messages, screenshots, request logs, or reporting configuration. Reporting quality should evolve with the framework. It is not a one-time setup task.

Reading an HTML Report Correctly

Reading an HTML report should follow a disciplined order. First, check the overall execution summary to understand whether the run failed broadly or only in a few scenarios. Next, identify the first failed scenario because later failures may be caused by the same root issue. Then open the failed scenario and inspect the failed step, exception message, and any attached evidence. Finally, compare the failure with recent code, data, or environment changes.

This order prevents wasted effort. If every scenario fails at the first login step, the root cause is probably authentication, environment availability, application startup, or a shared setup method. If only one scenario fails in a business assertion, the issue may be a product defect or test data mismatch. The report should guide the investigation instead of being treated as only a pass/fail scoreboard.

Using HTML Reports in Daily QA Work

In daily QA work, HTML reports are useful after local smoke runs, module regression runs, sprint validation, and defect verification. A tester can execute a focused tag such as @Smoke or @Customer, open the HTML report, and quickly review whether the expected behaviors passed. This is faster and cleaner than scanning raw console logs.

HTML reports also help when handing off failures to developers. Instead of describing a problem verbally, the tester can share the failed scenario name, failed step, error message, and report artifact from the build. Clear report evidence reduces back-and-forth and helps developers reproduce the issue faster. The value is highest when the scenario names and step text are already meaningful.

Using HTML Reports for Release Review

Before a release, teams often run smoke or regression suites and review the results. HTML reports provide a readable summary of that execution. They can show which critical business flows passed and which ones failed. QA leads can use the report to support release discussions, especially when paired with defect status, manual testing notes, and CI build information.

HTML reports should not be the only release artifact, but they are useful evidence. A release decision may also consider open defects, risk, test coverage, environment stability, performance results, and business sign-off. The report contributes automation execution evidence to that larger decision.

Handling Large HTML Reports

Large regression suites can generate large HTML reports. When hundreds or thousands of scenarios run, the report may become harder to open, slower to browse, and more difficult to analyze manually. This is one reason large teams often split execution by tags, modules, or suites. Smaller reports are easier to review and assign to the right owners.

If the report is too large, consider generating separate reports for smoke, API, UI, regression, and module-level executions. Keep JSON or XML outputs for full aggregation if needed. The goal is to provide useful visibility, not one massive file that nobody wants to open. Reporting should scale with the test suite.

Environment Details in Reports

Built-in HTML reports may not automatically show all environment details. In real projects, it is often useful to know the environment, browser, application version, API base URL, build number, branch, commit ID, test runner, and execution timestamp. These details help connect a report to the exact test context.

If built-in reports do not show enough environment information, teams can include context through CI artifact names, report folders, logs, attachments, or advanced reporting tools. Without environment details, a report may be difficult to interpret later. A failed scenario in QA may mean something different from the same failure in staging or a developer environment.

Failure Evidence and Attachments

HTML reports become more useful when they include evidence. For UI tests, that evidence is often screenshots. For API tests, it may be sanitized request and response bodies. For database or file-processing tests, it may include generated files, logs, or identifiers. Built-in report support depends on framework configuration, but the principle is consistent: useful evidence shortens debugging time.

Evidence should be focused. Attaching huge logs for every passing scenario makes reports heavy and noisy. A better practice is to attach detailed evidence on failure and keep passing results clean. Sensitive data should always be masked before attachment. Good evidence helps debugging without making reports unsafe or unreadable.

Troubleshooting Missing HTML Reports

If an HTML report is not generated, check the plugin configuration first. Confirm that the html: plugin is present and that the output path is valid. Then confirm that the runner actually executed. Check whether Maven cleaned the target directory after the report was generated, whether the CI job archived the wrong folder, or whether parallel execution caused report files to be overwritten.

Also check the Cucumber version and runner style. Some projects configure plugins through annotations, command-line options, JUnit platform properties, or build-tool configuration. If the project has multiple runners, make sure the runner being executed is the one with the report configuration. Reporting failures are usually configuration problems, not Cucumber execution problems.

Improving Report Failure Messages

HTML reports display assertion failures and exceptions, so the quality of those messages matters. A vague assertion message makes the report difficult to use. A clear assertion message tells the reader what was expected and what actually happened. For example, "Expected dashboard title Home but found Login" is much better than "expected true but was false."

Automation engineers should write validators and assertions with report readability in mind. If a response field is wrong, mention the field name. If a page title is wrong, show expected and actual values. If a data row failed, include the case name or row identifier. Better messages turn reports into actionable debugging tools.

HTML Reports and Test Ownership

In large teams, reports should help identify ownership. Tags, feature names, folder structure, and scenario names can indicate which team or module owns a failure. For example, failures under Payment Feature with @Payment tag can be routed to the payment team. Failures under Login Feature can go to authentication owners. This reduces delay in triage.

Built-in HTML reports may not provide advanced ownership dashboards, but clear organization still helps. If all scenarios are placed in generic features with unclear names, ownership is hard to determine. Good suite organization improves reporting even without advanced tools.

Interview-Ready Summary

HTML reports are built-in Cucumber reports that present execution results in a browser-friendly format. They display features, scenarios, steps, execution status, failure details, and execution time. HTML reports are generated using the HTML plugin configured in @CucumberOptions or equivalent Cucumber runner configuration.

Enterprise projects typically generate HTML reports together with JSON and JUnit XML reports to support both manual analysis and CI/CD integrations. Built-in HTML reports are useful for execution summaries, while advanced reporting tools are often adopted for dashboards, screenshots, historical reporting, and richer analytics.

Golden Rules

Generate HTML reports after every test execution. Store reports in the target directory, not in source folders. Generate HTML together with JSON and JUnit XML reports. Review failed steps and execution summaries before debugging. Use built-in HTML reports for execution summaries and advanced reporting tools when richer visualization and analytics are needed.

The practical takeaway is clear: HTML reports make Cucumber execution easier to understand after a run. They are simple, readable, browser-friendly, and valuable when combined with good Gherkin, clear failures, CI archiving, and supporting report formats.