Smoke Test Tagging in Cucumber JVM

What Is Smoke Test Tagging?

Smoke test tagging is the practice of marking the most critical Cucumber scenarios with the @Smoke tag so they can be executed independently from the rest of the automation suite. These scenarios validate whether the application is stable enough for deeper testing after a new build, deployment, environment refresh, or release candidate. In a Cucumber JVM framework, the @Smoke tag acts as a clear execution label that tells the runner, CI pipeline, and team which scenarios belong to the smoke suite.

In simple terms, @Smoke identifies the scenarios that must pass before detailed testing continues. A smoke test does not try to validate every rule, edge case, exception path, or rare workflow. It checks whether the most important functions are alive. If the smoke suite fails, the team usually stops broader regression execution because the build is not healthy enough to justify deeper testing.

Smoke test tagging is valuable because modern automation projects often contain hundreds or thousands of scenarios. Running everything after every small change may take too long. A smoke tag gives the team a fast, reliable subset that can run frequently. This fast subset helps detect broken builds early and prevents wasted time on long regression runs when the application is clearly unstable.

Good smoke tagging requires judgment. It is not enough to tag scenarios randomly as @Smoke. A smoke scenario should cover a core business capability or critical technical health check. The tag should be used consistently, reviewed regularly, and connected to CI execution. When done well, smoke tagging becomes one of the most useful controls in a Cucumber automation framework.

What Is Smoke Testing?

Smoke testing is a quick validation activity performed to confirm that the application is stable enough for further testing. The term comes from a basic hardware idea: if a machine starts without smoke, deeper testing can continue. In software, smoke testing answers one practical question: is the build healthy enough to test further?

A smoke suite normally validates application launch, login, key navigation, core workflows, basic data access, and major integration points. For an e-commerce application, smoke tests may include login, product search, add to cart, checkout availability, and order confirmation. For a banking application, smoke tests may include login, account summary, fund transfer initiation, and transaction history loading. For an API platform, smoke tests may include health checks, authentication, and a few critical endpoint responses.

Smoke testing is intentionally small. It is not the same as regression testing. Regression testing asks whether existing functionality still works across many areas and conditions. Smoke testing asks whether the build is usable enough to continue. If smoke tests fail, running the full regression suite may only produce hundreds of noisy failures caused by the same basic issue.

In Cucumber JVM, smoke testing becomes operational through tags. The scenarios that represent build health are marked with @Smoke. The runner or build command then executes only those scenarios. This gives the team a repeatable smoke suite instead of a manually selected set of tests.

Why Use Smoke Test Tags?

Smoke test tags are needed because large automation suites cannot always run fully after every change. Imagine a project with 2,500 Cucumber scenarios. Perhaps 150 scenarios are smoke tests and the remaining 2,350 are broader regression tests. Running all 2,500 after every build may take several hours. Running only @Smoke scenarios may take a few minutes and provide fast confidence that the application is not badly broken.

The workflow is straightforward. A new build is deployed. The CI pipeline runs @Smoke tests. If they pass, the team can proceed with full regression, exploratory testing, or release validation. If they fail, the team stops and investigates. This protects time and infrastructure because there is little value in running a long suite when the application cannot pass basic checks.

Smoke tags also make execution transparent. Instead of maintaining a separate hardcoded runner with selected feature paths, the team labels the important scenarios directly in feature files. Anyone reading the feature file can see that a scenario belongs to the smoke suite. Anyone reviewing the CI command can see that the pipeline is running @Smoke.

Another benefit is flexibility. A scenario can have multiple tags. A valid login scenario may be @Smoke, @UI, @Login, and @Critical. This allows the same scenario to participate in different execution views. It can run in smoke, UI, login-module, and critical-flow pipelines without duplication.

Basic Smoke Tag Syntax

The basic syntax is simple. Place @Smoke above the scenario that should belong to the smoke suite. The tag starts with the @ symbol and appears before the Scenario keyword.

@Smoke
Scenario: Valid login
  Given the user is on the login page
  When the user enters valid credentials
  Then the dashboard should be displayed

This marks the scenario as part of the smoke suite. When Cucumber is executed with a smoke tag expression, this scenario is selected. Scenarios without the @Smoke tag are skipped for that run.

Many teams use PascalCase for tag names, so @Smoke is preferred over inconsistent variations such as @smoke, @SMOKE, or @SmokeTest. The exact naming convention may vary by team, but consistency is mandatory. The CI pipeline will match the exact tag used in the feature file.

Feature-Level Smoke Tagging

A smoke tag can be placed at the feature level. When a tag is written above the Feature keyword, every scenario inside that feature inherits the tag. This is useful only when every scenario in the feature truly belongs to the smoke suite.

@Smoke
Feature: Login

  Scenario: Valid login
    Given the user has valid credentials
    When the user logs in
    Then the dashboard should be displayed

  Scenario: Logout
    Given the user is logged in
    When the user logs out
    Then the login page should be displayed

In this example, both scenarios are part of smoke because the feature-level tag applies to both. This can reduce repetition when a small feature file is intentionally designed only for smoke coverage.

However, feature-level smoke tagging should be used carefully. If a feature contains a mix of smoke, regression, negative, edge-case, and rare scenarios, putting @Smoke at the feature level is too broad. It will pull too many scenarios into the smoke suite and make the suite slower and less focused. Smoke should stay small, fast, and meaningful.

Scenario-Level Smoke Tagging

Scenario-level smoke tagging is the most common and safest approach. The tag is placed directly above only the scenarios that belong to smoke. This gives precise control inside feature files that contain many scenario types.

Feature: Login

  @Smoke
  Scenario: Valid login
    Given the user has valid credentials
    When the user logs in
    Then the dashboard should be displayed

  Scenario: Invalid login
    Given the user has invalid credentials
    When the user tries to log in
    Then an error message should be displayed

Here, only the valid login scenario belongs to smoke. The invalid login scenario may still be valuable, but it is likely regression or negative testing rather than smoke. This distinction keeps smoke execution focused on the most important build-health behavior.

Scenario-level tagging is also easier to review. A reviewer can ask whether each @Smoke scenario is truly critical. If a scenario is long, rare, unstable, or highly detailed, it may not belong in smoke even if it covers an important feature.

Smoke Suite Example

Consider a simple e-commerce feature. Not every scenario in the feature should be smoke. The smoke suite should include only the flows that confirm the application can perform essential actions.

Feature: E-Commerce

  @Smoke
  Scenario: User login
    Given the user has valid credentials
    When the user logs in
    Then the dashboard should be displayed

  @Smoke
  Scenario: Product search
    Given the user is on the product catalog
    When the user searches for a product
    Then matching products should be displayed

  @Smoke
  Scenario: Add product to cart
    Given the user is viewing an available product
    When the user adds the product to the cart
    Then the cart should contain the product

  Scenario: Apply discount coupon
    Given the user has items in the cart
    When the user applies an invalid coupon
    Then a coupon error should be displayed

In this example, login, search, and add-to-cart are smoke candidates because they represent basic application health. Applying an invalid coupon is useful, but it is not usually required to decide whether the build is stable enough for deeper testing. It belongs in regression or negative testing.

Typical Smoke Test Candidates

Good smoke candidates are scenarios that validate the application's most important and frequently used capabilities. They should give fast confidence that the build is usable. Common smoke candidates include application launch, user login, dashboard loading, product search, add to cart, checkout availability, user registration, API health check, database connectivity, and major page loading.

The exact smoke candidates depend on the domain. In a healthcare application, smoke may include patient search, appointment booking, and provider login. In a banking application, smoke may include account summary, transfer page loading, and transaction history. In a learning platform, smoke may include login, course listing, lesson launch, and progress saving.

A good smoke scenario should be stable, quick, and high value. It should not depend on rare data, long workflows, or complicated preconditions. If a smoke scenario frequently fails because of test instability rather than real build health, it weakens trust in the smoke suite and should be improved or removed.

What Should Not Be Smoke Tests?

Smoke suites should avoid edge cases, complex workflows, rare business paths, heavy negative testing, performance tests, security tests, long-running scenarios, and highly data-heavy validations. These tests may be important, but they are not the purpose of smoke testing. Smoke is a gate, not a complete quality assessment.

For example, a scenario that verifies five thousand products with multiple filters belongs in regression or performance-oriented testing, not smoke. A scenario that validates many invalid coupon combinations belongs in regression. A scenario that checks every field-level validation on a registration form belongs in detailed functional testing. A scenario that performs end-to-end order placement across several external systems may be too slow for smoke unless it is the single most critical business path and is stable enough to run frequently.

Overloading smoke with too many scenarios is a common mistake. Teams often start with a fast smoke suite, then gradually add more tests because every feature feels important. Eventually, smoke takes too long and stops serving its purpose. A smoke suite should remain intentionally small.

Combining Smoke with Other Tags

A scenario can have multiple tags. This is useful because smoke is only one classification. A scenario may also be part of a module, test layer, priority group, or ownership group.

@Smoke @UI @Login @Critical
Scenario: Valid login
  Given the user has valid credentials
  When the user logs in
  Then the dashboard should be displayed

This scenario belongs to the smoke suite, UI suite, login module, and critical tests. A CI job can run @Smoke to select all smoke tests. Another job can run @Smoke and @UI to run only UI smoke tests. A module team can run @Login to execute login scenarios.

Multiple tags should be meaningful, not decorative. If every scenario has too many tags, feature files become noisy. Use enough tags to support real execution, reporting, and ownership needs. Avoid adding tags only because they sound useful.

Running Smoke Tests with Tags

In Cucumber JVM, smoke tests can be executed with a tag expression. Depending on the runner and build tool, this may be configured in @CucumberOptions, Maven, Gradle, or CI variables. The key idea is that Cucumber receives the expression @Smoke and selects matching scenarios.

@CucumberOptions(
    features = "src/test/resources/features",
    glue = "stepdefinitions",
    tags = "@Smoke"
)
public class SmokeRunner {
}

Many teams avoid hardcoding tags in runner classes and instead pass them through Maven or CI:

mvn test -Dcucumber.filter.tags="@Smoke"

This dynamic approach is flexible because the same runner can execute smoke, regression, API, or critical scenarios depending on the command. It also keeps pipeline configuration clear. A build job named "Smoke Tests" can run exactly the @Smoke expression.

Smoke Tags in CI Pipelines

Smoke tagging is especially useful in CI/CD pipelines. After a build is deployed to a test environment, the pipeline can trigger the smoke suite. If the smoke suite passes, the pipeline may continue to regression execution, deployment promotion, or manual exploratory testing. If smoke fails, the pipeline can stop and notify the team.

This saves time and infrastructure. Running a full regression suite against a broken deployment may consume hours and produce hundreds of failures. A smoke gate fails fast and points the team toward the build-health problem. It also protects testers from wasting time analyzing failures caused by a known unstable build.

Smoke tags should be stable in CI. If the build job runs @Smoke, the tag name must be used consistently in feature files. If some scenarios use @smoke or @SmokeTest, they may be skipped. This is why tag naming conventions matter directly to pipeline reliability.

Smoke Tag Selection Criteria

Not every important scenario should be marked as smoke. A strong smoke candidate should satisfy several conditions. It should validate a critical function. It should be stable. It should be reasonably fast. It should have clear pass/fail meaning. It should not depend on rare data or fragile external systems unless that dependency is itself part of the build-health check.

A practical question is: if this scenario fails, would the team stop further testing? If the answer is yes, it may be a smoke candidate. If the answer is no and testing would continue anyway, the scenario may belong in regression rather than smoke.

Another useful question is: does this scenario prove that a major user journey can begin or complete? Login, landing page load, product search, cart addition, and core API health often answer yes. A minor UI alignment check or a rare negative validation usually answers no.

Smoke Test Size and Execution Time

A smoke suite should be small enough to run frequently. There is no universal number because project size differs, but the suite should complete quickly enough to provide fast feedback. If smoke takes nearly as long as regression, it is no longer functioning as smoke.

For many teams, a smoke suite should run in minutes, not hours. The exact limit may be decided by CI expectations. A pull request smoke run might need to finish under ten minutes. A post-deployment smoke run might allow more time if it validates several systems. The point is that the team should define an execution-time target and keep the suite within it.

When smoke grows too large, review each scenario. Remove detailed variations, unstable flows, duplicate coverage, and long-running paths. Keep only high-value checks. If a scenario is important but slow, consider whether it belongs in a nightly regression suite instead.

Smoke Tags and Regression Tags

Smoke and regression tags are related but not the same. Smoke is a small build-health suite. Regression is a broader suite that checks whether existing functionality still works after changes. A smoke scenario may also be part of regression, but not every regression scenario should be smoke.

@Smoke @Regression @UI @Login
Scenario: Successful login
  Given the user has valid credentials
  When the user logs in
  Then the dashboard should be displayed

This tagging style treats smoke as a subset of regression. It is a common approach. It allows a full regression run to include smoke tests, while still allowing a fast smoke run to execute only the most critical scenarios.

Some teams prefer to keep @Smoke and @Regression separate and use CI expressions to combine them when needed. Either approach can work, but it must be documented. The team should know whether smoke tests are automatically included in regression or require explicit selection.

Smoke Tags and Layer Tags

Smoke tests can exist at multiple layers. A UI smoke scenario validates browser-level user flow. An API smoke scenario validates a critical service endpoint. A database smoke scenario may validate connectivity or essential data availability. Layer tags help separate these forms of smoke.

@Smoke @API @HealthCheck
Scenario: Authentication service is available
  Given the authentication service is running
  When the client requests the health endpoint
  Then the service should return a healthy response

Using layer tags with smoke gives flexible execution. A team can run all smoke tests with @Smoke, only UI smoke tests with @Smoke and @UI, or only API smoke tests with @Smoke and @API. This is useful when different pipeline stages validate different layers.

Layer-based smoke design also helps diagnose failures. If API smoke passes but UI smoke fails, the issue may be in frontend, browser automation, UI deployment, or integration between UI and backend. If API smoke fails, the application may be broken at a deeper service level.

Smoke Tags and Hooks

Tags can be used with hooks, but teams should be careful. A tagged hook for @Smoke may perform additional technical setup, reporting, or environment checks for smoke scenarios. This can be useful when smoke runs require a specific base configuration.

@Before("@Smoke")
public void beforeSmokeScenario() {
    scenarioContext.setSuiteType("Smoke");
}

This kind of hook is acceptable because it handles technical metadata. However, a @Smoke hook should not hide business steps. It should not secretly log in, add products, submit orders, or validate outcomes. Smoke behavior should remain visible in Gherkin just like any other scenario behavior.

Using smoke tags to drive hidden business flow makes reports misleading and feature files incomplete. Tags should classify tests and support execution, not replace readable steps.

Common Smoke Tagging Mistakes

Tagging Too Many Scenarios

The most common mistake is adding @Smoke to too many scenarios. This usually happens because every feature feels important. The result is a slow smoke suite that no longer provides quick feedback. Smoke should remain small and focused.

Tagging Edge Cases as Smoke

Edge cases are valuable, but they usually belong in regression. Smoke should validate broad build health, not every unusual condition. Negative tests and rare data combinations should be added only when they represent a critical build gate.

Using Inconsistent Tag Names

@Smoke, @smoke, and @SmokeTest are different tags. Inconsistent names cause missed execution and confusing reports. Use one approved name consistently.

Keeping Flaky Tests in Smoke

A flaky smoke test damages trust in the pipeline. Smoke failures should mean the build may be unstable, not that the automation is unreliable. Flaky smoke tests should be fixed, moved, or quarantined with clear ownership.

Using Smoke Tags as Hidden Setup

A smoke tag should not secretly perform business flow through hooks. It should identify scenarios, not hide actions.

Maintaining the Smoke Suite

Smoke tagging is not a one-time activity. As the product changes, the smoke suite must be reviewed. New critical flows may be added. Old flows may become less important. Some scenarios may become too slow or unstable. Some modules may need stronger smoke coverage after architecture changes.

A good practice is to review smoke tags during release planning or major feature changes. Ask whether the current smoke suite still represents the most important application health checks. If the business has changed, smoke coverage should change too. For example, if a new payment method becomes the primary checkout path, a smoke scenario may need to cover it.

Smoke maintenance should also include execution-time review. If smoke duration keeps increasing, remove low-value scenarios or move them to regression. The suite should stay fast enough for frequent execution.

Smoke Tagging in Real Projects

In real projects, smoke tagging often becomes a release gate. A deployment pipeline may run smoke tests immediately after deploying to QA. If smoke passes, the environment is handed to testers. If smoke fails, the deployment may be rejected or rolled back. This makes smoke tagging a direct part of release confidence.

Because smoke tests influence release decisions, they should be reliable. A smoke scenario should have stable test data, strong synchronization, clear assertions, and minimal dependency on unpredictable external services. If external dependencies are unavoidable, their failures should be easy to diagnose.

Smoke tests should also produce useful failure evidence. Screenshots, logs, current URL, API responses, and clear report names help the team triage quickly. The goal is not only to fail fast but also to understand fast.

Smoke Tag Review Checklist

When reviewing a scenario marked as @Smoke, ask whether it validates a critical function, whether it is fast enough for frequent execution, whether it is stable, and whether its failure would stop further testing. If the answer to these questions is no, the scenario may not belong in smoke.

Also check whether the tag is placed at the correct level. If only one scenario in a feature is smoke, use scenario-level tagging. If every scenario in a feature is truly smoke, feature-level tagging may be acceptable. If only some examples in a scenario outline are smoke, use examples-level tagging or split the scenario for clarity.

Finally, check consistency. Use @Smoke exactly as defined by the team. Avoid duplicate names. Make sure CI commands, runner classes, reports, and documentation all refer to the same tag.

Ownership of Smoke Tests

Smoke tests should have clear ownership because they often block pipelines and influence release decisions. If a smoke scenario fails, the team should know who investigates it, which module it belongs to, and whether the failure is an application issue, data issue, environment issue, or automation issue. Without ownership, smoke failures can sit unresolved while the build remains blocked.

Ownership can be handled through module tags, team tags, or documentation. For example, a scenario tagged @Smoke @Checkout clearly belongs to the checkout area. If reports or dashboards support routing, the module tag can help notify the correct group. Some organizations also use tags such as @TeamPayments, but these should be maintained carefully because team structures change over time.

Each smoke scenario should also have a reason to exist. The team should be able to explain why it belongs in smoke and what risk it protects. If nobody can explain why a scenario is smoke, it may be a leftover from an old release or a test that belongs in regression instead. Clear ownership keeps the smoke suite meaningful and prevents it from becoming a dumping ground for important-sounding tests.

Best Practices

Keep the smoke suite small, fast, stable, and high value. Use @Smoke only for scenarios that validate core application health. Combine smoke with other tags such as @UI, @API, @Login, @Checkout, or @Critical when those categories add real execution or reporting value.

Prefer scenario-level smoke tagging unless every scenario in a feature belongs to smoke. Avoid tagging detailed negative cases, edge cases, long-running flows, or unstable tests as smoke. Keep smoke test data reliable and easy to reset. Make smoke failures actionable with clear assertions and useful diagnostics.

Run smoke tests early in CI/CD pipelines. Use smoke as a build-health gate before full regression. Review smoke tags regularly as the application changes. Remove scenarios that no longer represent critical health checks and add new scenarios when new core workflows become important.

Interview-Ready Explanation

Smoke test tagging in Cucumber JVM means marking critical scenarios with the @Smoke tag so they can be executed separately from the full regression suite. Smoke tests verify whether the application is stable enough for further testing after a build or deployment. If smoke tests fail, the team usually stops detailed testing and investigates the build.

The @Smoke tag can be applied at feature level, scenario level, or examples level, but scenario-level tagging gives the most precise control. Good smoke tests are fast, stable, business-critical, and high value. They should not include rare edge cases, long workflows, or unstable checks. Smoke tags are commonly used in CI pipelines to provide quick feedback before regression execution.

Summary

Smoke test tagging is a practical way to control fast build validation in Cucumber JVM. By marking critical scenarios with @Smoke, teams can run a focused suite that checks whether the application is healthy enough for deeper testing. This saves time, improves CI feedback, and prevents full regression runs against obviously broken builds.

The golden rule is to keep smoke small and meaningful. Tag only the scenarios that represent essential application health, use consistent tag naming, combine tags thoughtfully, and review the smoke suite regularly. A well-maintained @Smoke suite becomes a reliable first signal of build quality.