Environment-Based Tags in Cucumber JVM

What Are Environment-Based Tags?

Environment-based tags are Cucumber tags used to identify scenarios that are intended to run in a specific testing environment. Common examples include @QA, @SIT, @UAT, @Staging, @PreProd, and sometimes @Production for very limited non-destructive checks. These tags help teams select only the scenarios that are valid for the environment where the test suite is running.

In simple terms, environment-based tags indicate where a scenario should run. A scenario that uses dummy payment data may be valid in QA but not in UAT. A business approval scenario may be meaningful in UAT but not in a developer sandbox. A production smoke scenario may verify only that a page loads or a health endpoint responds, while destructive actions such as creating orders or deleting users should usually be avoided.

These tags are useful because environments are not always identical. They may have different data, integrations, permissions, feature flags, service endpoints, database states, email providers, payment gateways, and access controls. A scenario that passes in one environment may fail in another because the environment is configured differently, not because the application behavior is broken.

A good environment tagging strategy keeps test execution realistic. It prevents QA-only tests from running in production-like environments, prevents UAT-only checks from running in unstable QA environments, and gives CI pipelines a clean way to select the right scenarios for each deployment stage.

Why Environment-Based Tags Are Needed

Different environments exist for different purposes. A developer environment is used for local or early technical validation. QA is often used for active testing with flexible data and test integrations. SIT, or System Integration Testing, validates interactions between systems. UAT, or User Acceptance Testing, supports business validation. Staging or pre-production is usually close to production and used for final release confidence. Production is live and must be treated with extreme caution.

Because each environment has a different purpose, not every scenario belongs everywhere. In QA, testers may create many users, orders, claims, payments, and reports. In UAT, data may be more controlled because business users are validating workflows. In staging, integrations may be production-like, so test scenarios must avoid unsafe operations. In production, automated checks are usually limited to read-only or non-destructive smoke monitoring.

Without environment tags, teams may accidentally run the wrong scenarios in the wrong place. A scenario that deletes test data may be acceptable in QA but dangerous in UAT. A scenario that uses dummy cards may work in QA but fail in staging where payment services behave differently. Environment tags reduce this risk by making the intended execution environment visible in the feature file.

They also improve pipeline control. A CI job for QA can run @QA. A UAT validation job can run @UAT. A staging job can run @Staging and @Smoke. This creates a clear relationship between deployment stage and Cucumber execution.

Example Environment Setup

A typical application delivery flow may move through several environments. Each stage has a different stability level and a different testing purpose.

Developer
   |
   v
QA
   |
   v
SIT
   |
   v
UAT
   |
   v
Staging
   |
   v
Production

In this model, QA is usually more flexible and allows heavy test data creation. SIT focuses on integrations. UAT focuses on business acceptance. Staging confirms release readiness. Production checks are minimal and cautious. Environment tags help align scenarios with this flow.

For example, a payment scenario using a dummy gateway may be tagged @QA. A scenario validating integration with an external tax service may be tagged @SIT. A scenario for business approval of a customer workflow may be tagged @UAT. A final read-only release validation may be tagged @Staging or @ProductionSmoke depending on the team's convention.

Basic Environment Tag Syntax

The syntax is the same as any Cucumber tag. Place the environment tag above the feature, scenario, scenario outline, or examples block that should run in that environment.

@QA
Scenario: Verify test user login
  Given the test user has valid credentials
  When the test user logs in
  Then login should be successful

This scenario is marked for the QA environment. A runner or CI command can select it using @QA. If the same scenario is also part of smoke or regression, it can carry multiple tags.

@Smoke @QA @Login
Scenario: Verify test user login
  Given the test user has valid credentials
  When the test user logs in
  Then the dashboard should be displayed

Here, @Smoke describes the execution group, @QA describes the environment, and @Login describes the module. These tags work together because each one answers a different question.

Feature-Level Environment Tags

Feature-level environment tags are placed above the Feature keyword. They apply to every scenario in the feature file. This is useful when a feature file is intentionally written for one environment.

@UAT
Feature: Customer Management

  Scenario: Business user creates customer
    Given the business user has customer details
    When the business user creates the customer
    Then the customer should be available for approval

  Scenario: Business user updates customer
    Given an existing customer is available
    When the business user updates customer information
    Then the changes should be saved

Both scenarios inherit @UAT. This can be clean when the entire feature is designed for UAT validation. It avoids repeating the same tag above every scenario.

The risk is over-tagging. If the feature file contains scenarios intended for QA, UAT, and staging, a feature-level environment tag may classify too broadly. In mixed files, scenario-level tagging is safer.

Scenario-Level Environment Tags

Scenario-level environment tags are placed directly above individual scenarios. This provides precise control when a feature contains scenarios for different environments.

Feature: Customer

  @QA
  Scenario: Create customer with test data
    Given the tester has generated customer data
    When the tester creates the customer
    Then the customer should be saved

  @UAT
  Scenario: Business approval of customer
    Given a customer is pending approval
    When the business user approves the customer
    Then the customer should become active

The first scenario belongs to QA because it uses generated test data. The second belongs to UAT because it validates business approval. Scenario-level environment tags make this distinction visible and prevent accidental execution in the wrong environment.

Common Environment Tags

Common environment tags include @Dev, @QA, @Test, @SIT, @UAT, @Staging, @PreProd, and @Production. Some teams prefer longer names such as @ProductionSmoke or @PreProduction for clarity. The exact names should match the organization's environment vocabulary.

Teams should avoid using multiple names for the same environment. For example, if @Staging and @PreProd mean the same thing in the organization, using both will create confusion. If they are different stages, document the difference clearly. Environment names should be stable because CI pipelines often depend on them.

Real-Time Example

Consider a payment feature. Different scenarios may be valid in different environments because payment integrations vary by stage.

Feature: Payment

  @QA
  Scenario: Payment using dummy gateway
    Given the user has items in the cart
    And dummy payment details are available
    When the user completes payment
    Then the payment should be approved by the test gateway

  @UAT
  Scenario: Business approval of payment flow
    Given the business user reviews a payment workflow
    When the payment flow is executed with approved UAT data
    Then the business user should confirm the outcome

  @Staging
  Scenario: Final release validation for payment page
    Given the user opens the payment page
    When the page loads
    Then payment options should be displayed

The QA scenario uses a dummy gateway. The UAT scenario supports business approval. The staging scenario is safer and focused on final validation. Environment tags communicate those differences clearly.

Combining Environment Tags with Smoke

Environment tags are often combined with smoke tags. Smoke identifies critical build-health checks, while the environment tag identifies where those checks should run.

@Smoke @QA
Scenario: QA login smoke check
  Given the QA test user has valid credentials
  When the user logs in
  Then the dashboard should be displayed

A QA pipeline can run @Smoke and @QA. A staging pipeline can run @Smoke and @Staging. This allows the team to maintain smoke checks that are appropriate for each environment rather than forcing one smoke suite to fit all stages.

This is important because smoke tests may differ by environment. QA smoke may create test data. Staging smoke may be mostly read-only. Production smoke may be extremely limited. Combining tags makes this distinction precise.

Combining Environment Tags with Regression

Environment tags can also be combined with regression tags. Regression identifies tests that validate existing functionality, while the environment tag identifies where they are allowed or intended to run.

@Regression @UAT @Checkout
Scenario: Checkout with approved UAT data
  Given the user has approved UAT cart data
  When the user completes checkout
  Then the order should be confirmed

A UAT regression job can run @Regression and @UAT. A QA regression job can run @Regression and @QA. This avoids running environment-specific regression scenarios in incompatible environments.

Environment-specific regression should be used carefully. If a scenario can run safely in all environments, it may not need an environment tag. Too many environment tags can make the suite harder to maintain. Use them when the environment genuinely affects execution.

Environment Tags and Configuration

Environment tags should not replace configuration management. A tag indicates where a scenario should run, but configuration still defines URLs, credentials, endpoints, database connections, browser settings, feature flags, and service integrations. A scenario tagged @QA still needs the framework to load QA configuration correctly.

A clean framework separates these responsibilities. Tags select scenarios. Configuration tells the framework how to run in the selected environment. For example, a Maven command may pass both a tag expression and an environment property:

mvn test -Dcucumber.filter.tags="@Smoke and @QA" -Denv=qa

The tag expression selects QA smoke scenarios. The env property loads QA URLs and credentials. Both are needed. If the tag says QA but the configuration points to staging, the run is misleading and potentially unsafe.

Environment Tags and Test Data

Test data is one of the main reasons environment tags are useful. QA may allow generated users, dummy payments, fake emails, and resettable data. UAT may use controlled data approved by business users. Staging may use production-like data with strict rules. Production should use only safe, non-destructive checks.

A scenario that creates and deletes many records may be valid in QA but inappropriate in UAT. A scenario that depends on business-approved UAT data may fail in QA because the data does not exist. Environment tags make these constraints explicit.

Teams should document data expectations for each environment tag. For example, @QA scenarios may create their own data. @UAT scenarios may use pre-approved data. @Staging scenarios may avoid destructive writes. Clear expectations prevent accidental environment pollution.

Environment Tags and Feature Flags

Modern applications often use feature flags. A feature may be enabled in QA but disabled in UAT. Another feature may be enabled in staging for final validation but not yet available in production. Environment tags can help keep scenarios aligned with flag availability.

For example, a scenario for a new checkout experience may be tagged @QA while the feature is being tested. Later, when the feature reaches UAT, the same scenario may receive @UAT. When it becomes a normal feature across environments, the environment-specific tags may be removed or adjusted.

Environment tags should not become a permanent workaround for poor feature-flag management. They are useful for controlling execution while environments differ, but the framework should still have a clear understanding of which flags are expected in each environment.

Environment Tags and External Integrations

External integrations often behave differently by environment. QA may use mocks or sandboxes. SIT may connect multiple real test systems. UAT may use business-approved integration endpoints. Staging may be close to production. These differences directly affect which scenarios should run.

A payment gateway scenario using dummy card numbers may be correct in QA. A tax calculation scenario may require SIT because it depends on a separate tax service. An email delivery scenario may use a fake inbox in QA but a controlled mailbox in UAT. Environment tags help prevent invalid integration assumptions.

When integrations differ, reports should make the environment clear. A failure in @SIT may indicate an integration problem rather than a core application bug. Environment tags provide useful context for triage.

Environment Tags and Hooks

Environment tags can be used with hooks, but they should be used carefully. A tagged hook can perform technical setup required for a specific environment, such as loading test data, enabling diagnostics, or setting environment-specific report metadata.

@Before("@QA")
public void beforeQaScenario() {
    scenarioContext.setEnvironment("QA");
}

This is acceptable because it supports execution metadata. However, environment-tagged hooks should not hide business behavior. A @UAT hook should not silently perform business approval steps. A @QA hook should not secretly create application state that the scenario does not describe unless that setup is purely technical and clearly documented.

Hooks should remain lifecycle-oriented. Tags should classify scenarios and support technical setup, not replace readable Gherkin.

Environment Tags in CI Pipelines

CI pipelines are one of the main places where environment tags provide value. A deployment pipeline can choose the right Cucumber scenarios for each stage. After deploying to QA, it may run @Smoke and @QA. After deploying to UAT, it may run @Smoke and @UAT. Before release, it may run @Staging and @Regression or a smaller pre-production suite.

This makes the pipeline more accurate because it does not run scenarios that are invalid for the current environment. It also makes the pipeline easier to read. The command itself communicates intent.

mvn test -Dcucumber.filter.tags="@Smoke and @Staging" -Denv=staging

The tag expression selects staging smoke tests, while the environment property loads staging configuration. The pipeline should keep these aligned. Running @Staging tests against QA configuration is a process error.

Production Environment Tags

Production tags require special caution. Production is live, so automated tests must avoid destructive actions, fake data creation, test payments, test emails to real users, database cleanup, and any behavior that changes real customer data. If production checks are used, they are usually read-only smoke or monitoring checks.

Some teams avoid @Production entirely and use a more explicit tag such as @ProductionSmoke or @ReadOnlyProduction. This makes the intent safer. A production-tagged scenario should be reviewed carefully and approved by the team responsible for production operations.

Production scenarios should have clear safeguards. They should use dedicated safe accounts if accounts are needed. They should not place real orders unless the business has a controlled process. They should not delete data. They should have strong timeouts and clear alerts. Production automation should be boring, predictable, and safe.

When Not to Use Environment Tags

Environment tags should not be added to every scenario automatically. If a scenario can run safely and correctly in every test environment, it may not need an environment tag. Overusing environment tags creates unnecessary maintenance and complicated tag expressions.

Use environment tags when a scenario is environment-specific because of data, configuration, integrations, permissions, feature flags, or safety rules. Do not use them just because the test happened to be written while testing QA. A scenario that is valid across QA, SIT, UAT, and staging should be designed to run across those environments through configuration.

The best strategy is selective tagging. Environment tags should communicate a real constraint. If there is no constraint, a general smoke, regression, module, or layer tag may be enough.

Common Mistakes with Environment Tags

Using Environment Tags as Configuration

A tag should not be the only thing that controls URLs or credentials. Use configuration management for environment settings. Tags select scenarios; configuration controls runtime values.

Over-Tagging Every Scenario

Adding @QA, @UAT, and @Staging everywhere creates noise. Use environment tags only when environment differences matter.

Running Destructive Tests in Production

Production checks should be read-only or carefully controlled. Environment tags must not make unsafe production execution easy.

Using Inconsistent Environment Names

@UAT, @UserAcceptance, and @BusinessTesting may refer to the same stage. Choose one approved name and document it.

Forgetting Data Differences

A scenario may fail in UAT simply because QA data assumptions do not exist there. Environment tags should be paired with clear data strategy.

Maintaining Environment Tags

Environment tags need maintenance because environments evolve. A scenario that was QA-only during early development may become valid in UAT later. A UAT scenario may become part of staging validation. A feature flag may be enabled in all environments, making an environment-specific tag unnecessary.

Review environment tags during release planning and environment changes. If a new integration is added to SIT, check which scenarios should receive @SIT. If a staging environment becomes production-like, review whether write-heavy scenarios should be excluded. If UAT data changes, update affected scenarios and documentation.

Environment tag maintenance should also include CI commands. If a tag is renamed from @PreProd to @Staging, pipeline expressions, documentation, and reports must be updated together. Otherwise, scenarios may be skipped silently.

Governance for Environment-Based Tags

Environment-based tags should have governance because they can affect real environments, shared data, and release workflows. A tag such as @QA may seem harmless, but a tag such as @Staging or @Production can decide whether automation touches a sensitive environment. Teams should define who can add environment tags, who reviews them, and what safety rules apply to each environment.

A practical governance model starts with an approved tag dictionary. The dictionary should list allowed environment tags, their meaning, the environments they map to, and the type of scenarios that can use them. For example, @QA may allow data creation and cleanup, @UAT may require business-approved data, @Staging may allow only controlled release checks, and @ProductionSmoke may allow only read-only validations.

Code review should include environment-tag review. When a scenario is marked with @UAT, reviewers should ask whether the test data exists in UAT and whether the scenario is appropriate for business validation. When a scenario is marked with @Staging, reviewers should ask whether it is safe for a production-like environment. When a scenario is marked with @Production, reviewers should be stricter and confirm that the test is non-destructive and approved.

Governance also means keeping environment tags aligned with access control. If only certain users can run production checks, the CI pipeline should enforce that. If staging tests require special approvals, the pipeline should not allow anyone to trigger them casually. Tags make selection easy, so process controls must make unsafe execution difficult.

Good governance does not need to be heavy. A short documented standard, clear naming conventions, code review checks, and controlled CI jobs are often enough. The goal is to prevent environment tags from becoming casual labels that accidentally create risk.

Migrating Scenarios Across Environments

Scenarios often move through environments as features mature. A new feature may begin in QA with @QA because the implementation is still changing and the data is artificial. Later, when the feature is stable enough for business review, some scenarios may receive @UAT. Before release, a smaller safe subset may receive @Staging. After release, a very limited read-only check may become part of production monitoring.

This migration should be intentional. Do not simply keep adding environment tags as a scenario moves forward. If a scenario is no longer QA-specific, remove @QA if it creates confusion. If a scenario becomes valid across multiple environments, consider whether it needs environment tags at all or whether configuration can make it portable. Environment tags should describe real constraints, not historical movement.

When migrating a scenario to a new environment, check data, integrations, credentials, permissions, feature flags, and cleanup behavior. A scenario that creates data safely in QA may be unsafe in UAT. A scenario that uses dummy payment data in QA may need approved sandbox data in SIT. A scenario that verifies email in QA may not work in staging if emails are suppressed or routed differently.

Migration also affects CI. If a scenario receives @UAT, the UAT pipeline may start running it immediately. That means the scenario must be stable, the data must be available, and the expected result must match UAT configuration. Tag changes should be treated as execution changes, not just documentation updates.

A mature team reviews environment movement during release planning. It asks which scenarios remain QA-only, which are ready for UAT, which should be part of staging release validation, and which, if any, are safe for production smoke. This keeps the automation suite aligned with the delivery lifecycle.

Auditing Environment Tags

An environment tag audit helps keep the suite accurate. Start by listing all environment tags used in feature files. Look for duplicates such as @PreProd and @Staging, inconsistent casing such as @uat and @UAT, and outdated tags for environments that no longer exist. Then compare the tags with actual CI jobs and configuration names.

The audit should also identify scenarios that are environment-tagged without a clear reason. If a scenario marked @QA can run safely in every environment through configuration, the tag may be unnecessary. If a scenario marked @UAT uses QA-only test data, the tag is wrong. If a scenario marked @Production writes data, it needs immediate review.

Reports can reveal environment tag problems. If a UAT report contains scenarios that business users do not recognize, the tagging may be too broad. If a staging smoke report misses critical release checks, some scenarios may be missing @Staging. If production checks are noisy or flaky, they may be too complex for production monitoring.

Environment tag audits should happen whenever environments are renamed, merged, refreshed, or reconfigured. They should also happen when CI pipelines change. A tag strategy is only useful when feature files, configuration files, CI jobs, and real environment behavior remain aligned.

Environment Tag Review Checklist

When reviewing an environment tag, ask whether the scenario truly depends on that environment. Does it require environment-specific data? Does it use a specific integration? Does it rely on feature flags or permissions available only in that stage? Is it unsafe in other environments? If the answer is yes, the environment tag is useful.

Also check whether the tag is placed at the correct level. If every scenario in a feature is UAT-only, feature-level @UAT may be clean. If only one scenario is UAT-specific, use scenario-level tagging. If only one examples block is environment-specific, examples-level tagging may be the best choice.

Finally, verify that the tag name matches the approved convention and that CI passes matching environment configuration. Tags and runtime configuration must agree.

Best Practices

Use environment tags only when environment differences affect execution. Keep environment names consistent, business-readable, and aligned with the organization's actual delivery stages. Document approved tags such as @QA, @SIT, @UAT, @Staging, and @PreProd.

Separate scenario selection from configuration. Use tags to select environment-appropriate scenarios and configuration properties to load URLs, credentials, endpoints, and environment-specific settings. Keep CI commands explicit so it is clear which tags and environment values are being used.

Be extremely cautious with production tags. Keep production checks non-destructive, reviewed, and limited. Avoid broad write operations in production. Review environment tags regularly as feature flags, integrations, and data strategies change.

Real-Time Framework Example

A real Cucumber JVM framework may support environment selection through a build parameter and scenario selection through tags. For example, a QA smoke job might run:

mvn test -Dcucumber.filter.tags="@Smoke and @QA" -Denv=qa

A UAT regression job might run:

mvn test -Dcucumber.filter.tags="@Regression and @UAT" -Denv=uat

A staging pre-release job might run:

mvn test -Dcucumber.filter.tags="@Smoke and @Staging" -Denv=staging

In each case, the tag expression and environment configuration are aligned. This makes execution clear and safer. The framework selects the right scenarios and loads the right environment settings.

Interview-Ready Explanation

Environment-based tags in Cucumber JVM are tags used to mark scenarios that should run in specific environments such as QA, SIT, UAT, staging, or production. They help teams execute only the scenarios that are valid for a given environment, especially when data, configurations, integrations, permissions, and feature flags differ across stages.

Environment tags can be applied at feature level, scenario level, scenario outline level, or examples level. They are often combined with tags such as @Smoke, @Regression, @UI, @API, and module tags. A good framework uses tags for scenario selection and separate configuration management for URLs, credentials, and environment settings.

Summary

Environment-based tags help Cucumber JVM teams run the right scenarios in the right testing environment. They are useful when environments differ by data, integrations, configuration, permissions, feature flags, or safety rules. They make CI pipelines clearer and reduce the risk of running invalid or unsafe tests.

The golden rule is to use environment tags only when the environment truly matters. Keep names consistent, align tags with configuration, avoid over-tagging, and treat production checks with strict caution. When environment tags are designed well, test execution becomes safer, more focused, and easier to understand.