← Volver al listado de tecnologías ← Índice de Gherkin

Tags y organización

15 de mayo de 2026 Por: Artiko

gherkintagsejecucion-selectivaorganizacion

Tags y organización

Los tags son etiquetas que se aplican a Features, Scenarios y Outlines. Empiezan con @ y permiten:

Ejecutar subconjuntos de la suite (smoke, wip, integration)
Agrupar por dominio (auth, billing, cart)
Trazar a requisitos (REQ-AUTH-001) o bugs (BUG-3214)
Aplicar hooks específicos (ejecutar Before solo en scenarios con cierto tag)
Definir comportamiento por entorno (smoke en dev, full en staging)

Sintaxis

@auth @critical
Feature: Login

  @happy-path @REQ-AUTH-001
  Scenario: Credenciales válidas
    Given ...

  @error @REQ-AUTH-002
  Scenario: Credenciales inválidas
    Given ...

  @wip
  Scenario Outline: Casos edge en desarrollo
    ...
    Examples:
      | ... |

Tags arriba de la línea de Feature/Scenario/Scenario Outline
Múltiples tags separados por espacio
Heredan de Feature a Scenarios (un scenario hereda los tags de su feature)

Convenciones comunes

Por etapa del pipeline

Tag	Significado
`@smoke`	Suite rápida que se ejecuta en cada commit
`@regression`	Suite completa para release candidate
`@nightly`	Suite extendida, ejecución nocturna
`@wip`	Work in progress, no se ejecuta en CI
`@manual`	No se ejecuta automatizado
`@flaky`	Marcado como inestable, requiere atención
`@skip`	Saltar temporalmente (con razón en comentario)

Por dominio

Tag	Dominio
`@auth`	Autenticación, sesiones
`@billing`	Facturación, pagos
`@cart`	Carrito, checkout
`@admin`	Panel administrativo
`@api`	Tests de API
`@ui`	Tests E2E de UI

Trazabilidad

Tag	Significado
`@REQ-AUTH-001`	Cubre el requisito EARS REQ-AUTH-001
`@JIRA-1234`	Cubre la tarjeta JIRA-1234
`@BUG-3214`	Regresión del bug 3214
`@compliance:PCI`	Cubre control de compliance PCI

Por característica del scenario

Tag	Significado
`@happy-path`	Camino feliz, sin errores
`@error`	Caso de error o excepción
`@boundary`	Casos límite
`@performance`	Test de performance
`@security`	Test de seguridad
`@a11y`	Test de accesibilidad

Ejecución selectiva

Cucumber-JS

# Solo @smoke
cucumber-js --tags "@smoke"

# Smoke pero NO wip
cucumber-js --tags "@smoke and not @wip"

# Smoke O regression
cucumber-js --tags "@smoke or @regression"

# Sin ningún wip ni manual
cucumber-js --tags "not @wip and not @manual"

# Auth Y critical
cucumber-js --tags "@auth and @critical"

# Auth, pero no UI
cucumber-js --tags "@auth and not @ui"

behave (Python)

# Solo @smoke
behave --tags=@smoke

# Smoke pero NO wip
behave --tags=@smoke --tags=~@wip

# Smoke O regression
behave --tags="@smoke,@regression"

# Multiple expresiones (AND)
behave --tags=@smoke --tags=@auth

Nota: la sintaxis de behave usa , para OR y múltiples --tags para AND. Cucumber-JS usa expresiones booleanas más legibles.

Tags en CI/CD

Configuración típica:

# .github/workflows/ci.yml

jobs:
  smoke:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
      - run: npm ci
      - run: npx cucumber-js --tags "@smoke and not @wip"

  regression:
    runs-on: ubuntu-latest
    if: github.event_name == 'pull_request'
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
      - run: npm ci
      - run: npx cucumber-js --tags "@regression and not @wip"

Hooks por tag

Aplicar setup específico solo a scenarios con cierto tag.

Cucumber-JS:

import { Before, After } from '@cucumber/cucumber'

Before({ tags: '@db' }, async function () {
  await truncateAllTables()
  await seedDb()
})

After({ tags: '@browser' }, async function () {
  await this.browser.close()
})

Before({ tags: '@admin and not @api' }, async function () {
  this.user = await createAdminUser()
})

behave (Python):

# features/environment.py

def before_scenario(context, scenario):
    if 'db' in scenario.tags:
        truncate_all_tables()
        seed_db()

    if 'admin' in scenario.tags and 'api' not in scenario.tags:
        context.user = create_admin_user()

def after_scenario(context, scenario):
    if 'browser' in scenario.tags:
        context.browser.close()

Tags en Outline + Examples

Los tags se aplican a la plantilla y/o a tablas Examples específicas:

@validation
Scenario Outline: Password strength
  When escribo "<password>"
  Then strength es "<expected>"

  @core-cases @smoke
  Examples: Casos comunes
    | password    | expected |
    | abc         | weak     |
    | abcdef123   | medium   |

  @edge-cases @nightly
  Examples: Casos edge
    | password                                                       | expected |
    | aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa   | weak     |
    | Abc!#$%^&*()1234567890qwertyuiopasdfghjkl                      | strong   |

Smoke ejecuta solo los casos comunes; nightly también los edge.

Anti-patrones

1. Tags inventados ad-hoc

- @important
- @maybe-flaky
- @check-this
+ # Definir un vocabulario fijo y documentarlo

Si cada autor inventa tags, la suite se vuelve caótica.

2. Tags sin documentación

- @level-3-edge
- ¿qué significa? ¿quién lo definió? ¿cuándo se ejecuta?
+ # Mantener un archivo TAGS.md con todos los tags y su significado

3. Tags como descripción del scenario

- @scenario-for-when-user-clicks-the-button
+ # eso va en el título del scenario, no en un tag

4. Demasiados tags

- @auth @login @form @password @validation @critical @smoke @regression @REQ-001 @REQ-002 @REQ-003
- Scenario: ...
+ # 3-5 tags es razonable; más es ruido

Tags para feature flags

Tags útiles para gestionar features en desarrollo:

@feature-flag:new-checkout
Scenario: Nuevo flujo de checkout
  ...

El runner activa el feature flag antes del scenario:

Before({ tags: '@feature-flag\\:new-checkout' }, async function () {
  await this.featureFlags.enable('new-checkout')
})

After({ tags: '@feature-flag\\:new-checkout' }, async function () {
  await this.featureFlags.disable('new-checkout')
})

Documentar tu vocabulario de tags

Archivo TAGS.md en el repo:

# Tags vocabulario

## Etapas
- `@smoke`: suite rápida (< 2 min total). Se ejecuta en cada commit.
- `@regression`: suite completa para release candidate.
- `@wip`: work in progress. No se ejecuta en CI.

## Dominios
- `@auth`, `@billing`, `@cart`, `@admin`

## Tipo de test
- `@api`, `@ui`, `@integration`, `@e2e`

## Trazabilidad
- `@REQ-XXX-NNN`: cubre el requisito EARS XXX-NNN
- `@JIRA-NNNN`: cubre la tarjeta de Jira NNNN
- `@BUG-NNNN`: regresión del bug NNNN

## Característica
- `@happy-path`, `@error`, `@boundary`, `@security`

Cualquier developer/QA puede leer este archivo y entender el vocabulario.

Diagrama: ejecución filtrada

flowchart TD
    All[Suite completa<br/>500 scenarios] -->|--tags "@smoke and not @wip"| Filter[Filtro]
    Filter --> Sub[Subconjunto<br/>40 scenarios]
    Sub --> Run[Ejecutar]
    Run --> Report[Reporte]

Resumen

Tags = @etiqueta aplicada a Feature/Scenario/Outline
Ejecución selectiva via --tags "<expresión>"
Hooks específicos por tag (Before({ tags: '@db' }))
Convenciones por etapa, dominio, trazabilidad, característica
Documentá tu vocabulario en TAGS.md

En el siguiente capítulo cubrimos Data Tables y Doc Strings.