📝 CAPÍTULO 07: ESPECIFICAÇÃO DE REQUISITOS (ERS E USER STORIES)

🎯 1. Objetivos de Aprendizagem & Competências

Estimativa de Dedicação: 2 horas de estudo autoguiado.
Ao final deste capítulo, você será capaz de:

• 🔹 Compreender a estrutura de uma Especificação de Requisitos de Software (ERS / SRS) segundo as normas IEEE 830 e ISO/IEC/IEEE 29148.
• 🔹 Formular Histórias de Usuário (User Stories) segundo o acrônimo INVEST (Independent, Negotiable, Valuable, Estimable, Small, Testable).
• 🔹 Escrever Critérios de Aceite estruturados utilizando a sintaxe Gherkin / BDD (Dado / Quando / Então).
• 🔹 Implementar testes automatizados em Python 3.11+ com pytest que validam diretamente os cenários descritos em Gherkin.

🏢 2. Cenário Corporativo & Estudo de Caso (TecProExpress)

Na TecProExpress, um cliente corporativo de grande porte assinou um contrato para integração de API de cálculo de fretes em tempo real. No entanto, o desenvolvedor backend implementou a resposta retornando prazos em dias úteis, enquanto o cliente esperava dias corridos.

O Desafio: A ausência de critérios de aceite inequívocos na ERS gerou 3 semanas de retrabalho e desgaste comercial. Como Engenheiro de Software, você deve formalizar a especificação através de User Stories claras e cenários executáveis em Gherkin que sirvam como contrato técnico e base de testes automatizados.

🧠 3. Fundamentação Teórica & Modelos Visuais

3.1. ERS Tradicional (IEEE 830) vs. User Stories Ágeis (INVEST)

A documentação de requisitos evoluiu de especificações volumosas para artefatos enxutos e orientados a valor de negócio:

flowchart TD
    subgraph MODELOS_ESPECIFICACAO ["EVOLUÇÃO DA ESPECIFICAÇÃO"]
        direction LR
        ERS["📄 ERS Tradicional (IEEE 830)<br>• Seções exaustivas<br>• Contrato formal rígido<br>• Ideal para sistemas críticos"]
        US["📋 User Story Ágil (INVEST)<br>• Como [ator] Quero [meta] Para [benefício]<br>• Critérios de Aceite em Gherkin<br>• Conversação contínua"]
    end
    style ERS fill:#e1f5fe,stroke:#0284c7
    style US fill:#dcfce7,stroke:#16a34a

3.2. A Tríade da User Story: Os 3 Cs de Ron Jeffries

Uma História de Usuário completa é composta por três elementos:

1. Cartão (Card): A descrição sintética no formato "Como... Quero... Para que...".
2. Conversa (Conversation): A discussão entre o Product Owner e a equipe técnica para detalhar nuances.
3. Confirmação (Confirmation): Os Critérios de Aceite que determinam quando a história está concluída.

flowchart LR
    C1["📇 Cartão (Card)<br>Como [Ator] Quero [Ação] Para [Benefício]"] --> C2["🗣️ Conversa (Conversation)<br>Alinhamento técnico & regras"]
    C2 --> C3["✅ Confirmação (Confirmation)<br>Cenários BDD / Critérios de Aceite"]
    
    style C1 fill:#e0f2fe,stroke:#0284c7
    style C2 fill:#ede7f6,stroke:#5e35b1
    style C3 fill:#dcfce7,stroke:#16a34a

3.3. Sintaxe BDD / Gherkin (Dado - Quando - Então)

Cenário: Cálculo de frete expresso para capitais
  Dado que o cliente está autenticado na API
  E o endereço de destino pertence à capital "São Paulo"
  Quando o cliente solicita o frete de um pacote de 2.0 kg
  Então o sistema deve retornar o valor de R$ 15.00
  E o prazo de entrega deve ser de "1 dia útil"

💻 4. Aplicação Prática & Código Executável (Python 3.11+)

Implementação do teste automatizado com Pytest traduzindo os cenários Gherkin (BDD).

📋 Pré-requisitos e Instalação

No terminal do seu ambiente virtual, instale o executor de testes Pytest:

pip install pytest

💻 Código Completo e Autocontido (test_calculo_frete_bdd.py)

Crie o arquivo test_calculo_frete_bdd.py e insira o código abaixo integralmente:

"""
Módulo: test_calculo_frete_bdd.py
Domínio: Testes de aceitação automatizados espelhando cenários BDD.
Stack: Python 3.11+ | Pytest
"""
from decimal import Decimal
import pytest

# Implementação do serviço de frete
def calcular_frete_entrega(peso_kg: Decimal, eh_capital: bool, expresso: bool) -> tuple[Decimal, int]:
    """Retorna (valor_reais, prazo_dias_uteis)."""
    if peso_kg <= Decimal("0.0"):
        raise ValueError("Peso inválido.")

    valor_base = Decimal("10.00") + (peso_kg * Decimal("2.50"))
    prazo = 3

    if eh_capital:
        prazo -= 1
    if expresso:
        valor_base *= Decimal("1.30")
        prazo = 1

    return (valor_base.quantize(Decimal("0.01")), prazo)

# --- CENÁRIOS BDD IMPLEMENTADOS COM PYTEST ---
def test_cenario_frete_expresso_capital():
    # Dado: Pacote de 2.0 kg para Capital em modo Expresso
    peso = Decimal("2.0")

    # Quando: Solicita o frete
    valor, prazo = calcular_frete_entrega(peso_kg=peso, eh_capital=True, expresso=True)

    # Então: Valida valor e prazo
    assert valor == Decimal("19.50")  # (10 + 5) * 1.30 = 19.50
    assert prazo == 1

def test_cenario_frete_convencional_interior():
    valor, prazo = calcular_frete_entrega(peso_kg=Decimal("1.0"), eh_capital=False, expresso=False)
    assert valor == Decimal("12.50")
    assert prazo == 3

if __name__ == "__main__":
    v, p = calcular_frete_entrega(Decimal("2.0"), True, True)
    print(f"✅ Cenário Validado: Frete R$ {v:.2f} em {p} dia(s) útil(eis)")

    print("\n🧪 Disparando suíte automatizada de cenários BDD com Pytest:")
    pytest.main(["-v", __file__])

🚀 Como Executar

Execute diretamente com Python ou pelo CLI do Pytest:

# Execução direta com Python (executa lógica e testes)
python test_calculo_frete_bdd.py

# Ou execução formal pelo Pytest
pytest -v test_calculo_frete_bdd.py

🖥️ Saída Esperada no Terminal

✅ Cenário Validado: Frete R$ 19.50 em 1 dia(s) útil(eis)

🧪 Disparando suíte automatizada de cenários BDD com Pytest:
============================= test session starts =============================
test_calculo_frete_bdd.py::test_cenario_frete_expresso_capital PASSED    [ 50%]
test_calculo_frete_bdd.py::test_cenario_frete_convencional_interior PASSED [100%]
============================== 2 passed in 0.04s ==============================

💡 5. Checkpoint de Engenharia & Boas Práticas

🔗 6. Conexão com os Projetos Integradores

🧪 7. Quiz de Fixação e Autoavaliação (Formative Assessment)

🛠️ 8. Ponte para a Ação: Laboratório Prático

📌 9. Resumo Executivo & Key Takeaways

• ERS vs User Story: A ERS tradicional documenta o contrato exaustivo (IEEE 830); as User Stories documentam a intenção de valor de forma incremental.
• INVEST: Guia de excelência para granularidade e qualidade de histórias de backlog.
• BDD & Gherkin: Linguagem comum entre desenvolvedores, testadores e analistas de negócio (Dado / Quando / Então).
• Especificação Executável: Testes com Pytest transformam critérios de aceite em garantias automáticas contra regressão.