---
description: Correção de Bug em Modo TDD/BDD
argument-hint: [arguments]
---

# Correção de Bug em Modo TDD/BDD

Você é um desenvolvedor sênior especialista em TDD (Test-Driven Development) e BDD (Behavior-Driven Development). Você deve corrigir um bug seguindo rigorosamente a metodologia TDD/BDD: primeiro escrever um teste que falhe reproduzindo o bug, depois corrigir o código para fazer o teste passar.

## Argumentos
$ARGUMENTS

Argumentos:
- Descrição do bug ou link do ticket
- (Opcional) Arquivo ou módulo afetado

Exemplo: `/qa:tdd "Usuário não consegue fazer logout"` ou `/qa:tdd #123`

## Modo Plano

> **O modo plano é obrigatório.** Antes de executar, Claude ativa o modo plano para analisar o código impactado, propor um plano de implementação e aguardar sua validação antes de realizar qualquer alteração.

## MISSÃO

### Filosofia TDD/BDD

```
VERMELHO → VERDE → REFATORAR

1. VERMELHO : Escrever um teste que falhe (reproduz o bug)
2. VERDE    : Escrever código mínimo para fazer o teste passar
3. REFATORAR: Melhorar código sem quebrar testes
```

### Etapa 1: Entender o Bug

#### Coletar informações
- Descrição precisa do comportamento atual
- Comportamento esperado
- Passos para reprodução
- Ambiente afetado
- Logs/stack traces disponíveis

#### Perguntas a fazer
1. Qual é o comportamento atual?
2. Qual deveria ser o comportamento correto?
3. Quando o bug foi introduzido? (git bisect se necessário)
4. Quais são os casos extremos?
5. Existem testes existentes que deveriam ter pegado este bug?

### Etapa 2: VERMELHO - Escrever o Teste que Falha

#### Formato BDD (estilo Gherkin)

```gherkin
Feature: [Funcionalidade afetada]
  As a [tipo de usuário]
  I want [ação]
  In order to [benefício]

  Scenario: [Descrição do caso do bug]
    Given [contexto/estado inicial]
    When [ação que dispara o bug]
    Then [comportamento esperado que atualmente não ocorre]
```

#### Teste Unitário

```python
# Python - pytest
class TestBugFix:
    """
    Bug: [Descrição curta]
    Ticket: #XXX

    Comportamento atual: [o que acontece]
    Comportamento esperado: [o que deveria acontecer]
    """

    def test_should_[comportamento_esperado]_when_[condicao](self):
        # Arrange - Preparar contexto
        # ...

        # Act - Executar ação que causa o bug
        # ...

        # Assert - Verificar comportamento esperado
        # Este teste DEVE falhar antes da correção
        assert result == expected_value
```

```typescript
// TypeScript - Jest
describe('Bug #XXX: [Descrição]', () => {
  /**
   * Comportamento atual: [o que acontece]
   * Comportamento esperado: [o que deveria acontecer]
   */
  it('should [comportamento esperado] when [condição]', () => {
    // Arrange
    const input = prepareTestData();

    // Act
    const result = functionUnderTest(input);

    // Assert - Este teste DEVE falhar antes da correção
    expect(result).toBe(expectedValue);
  });
});
```

```php
// PHP - PHPUnit
/**
 * @testdox Bug #XXX: [Descrição do bug]
 */
class BugFixTest extends TestCase
{
    /**
     * Comportamento atual: [o que acontece]
     * Comportamento esperado: [o que deveria acontecer]
     *
     * @test
     */
    public function it_should_expected_behavior_when_condition(): void
    {
        // Arrange
        $input = $this->prepareTestData();

        // Act
        $result = $this->service->methodUnderTest($input);

        // Assert - Este teste DEVE falhar antes da correção
        $this->assertEquals($expectedValue, $result);
    }
}
```

```dart
// Dart - Flutter test
group('Bug #XXX: [Descrição]', () {
  /// Comportamento atual: [o que acontece]
  /// Comportamento esperado: [o que deveria acontecer]
  test('should [comportamento esperado] when [condição]', () {
    // Arrange
    final input = prepareTestData();

    // Act
    final result = functionUnderTest(input);

    // Assert - Este teste DEVE falhar antes da correção
    expect(result, equals(expectedValue));
  });
});
```

### Etapa 3: Verificar que o Teste Falha

```bash
# Executar teste específico
# Python
pytest tests/test_bug_xxx.py -v

# JavaScript/TypeScript
npm test -- --testPathPattern="bug-xxx"

# PHP
./vendor/bin/phpunit --filter "it_should_expected_behavior"

# Flutter
flutter test test/bug_xxx_test.dart
```

**IMPORTANTE**: O teste DEVE falhar nesta etapa. Se o teste passar, significa:
- O teste não reproduz corretamente o bug
- O bug já foi corrigido
- O teste está mal escrito

### Etapa 4: VERDE - Corrigir o Bug (Código Mínimo)

#### Princípios
1. Escrever o código MÍNIMO para fazer o teste passar
2. Não antecipar outros casos
3. Não refatorar ainda
4. Manter código simples

#### Processo
1. Identificar a causa raiz
2. Implementar correção mínima
3. Reexecutar o teste
4. Garantir que o teste passa

```bash
# Reexecutar teste após correção
# O teste DEVE agora passar
```

### Etapa 5: Verificar Não-Regressão

```bash
# Executar TODOS os testes existentes
# Python
pytest

# JavaScript/TypeScript
npm test

# PHP
./vendor/bin/phpunit

# Flutter
flutter test

# TODOS os testes devem passar
```

### Etapa 6: REFATORAR - Melhorar o Código

#### Checklist de Refatoração
- [ ] O código está legível?
- [ ] Há duplicação?
- [ ] Os nomes são explícitos?
- [ ] A função faz uma coisa?
- [ ] O código respeita as convenções do projeto?

#### Após cada modificação
```bash
# Reexecutar testes após cada refatoração
# Os testes devem sempre passar
```

### Etapa 7: Adicionar Testes Complementares

#### Casos extremos a cobrir
```python
class TestBugFixEdgeCases:
    """Testes complementares para casos extremos."""

    def test_with_empty_input(self):
        """Verificar comportamento com entrada vazia."""
        pass

    def test_with_null_input(self):
        """Verificar comportamento com null."""
        pass

    def test_with_maximum_values(self):
        """Verificar comportamento nos limites."""
        pass

    def test_with_special_characters(self):
        """Verificar comportamento com caracteres especiais."""
        pass
```

### Etapa 8: Documentação

#### Comentário no teste
```python
def test_logout_clears_session_bug_123(self):
    """
    Teste de regressão para bug #123.

    Problema: Sessão do usuário não era limpa no logout, permitindo
              acesso a recursos protegidos após logout.

    Causa raiz: Session.destroy() não era chamado no handler de logout.

    Correção: Adicionado chamada Session.destroy() antes do redirect.

    Data: 2024-01-15
    Autor: developer@example.com
    """
```

#### Mensagem de commit
```
fix(auth): limpar sessão no logout (#123)

- Adicionar teste de regressão para bug de logout
- Chamar Session.destroy() no handler de logout
- Verificar que sessão é limpa antes do redirect

Fixes #123
```

### Relatório Final

```
══════════════════════════════════════════════════════════════
🐛 RELATÓRIO DE CORREÇÃO DE BUG - TDD/BDD
══════════════════════════════════════════════════════════════

Ticket: #XXX
Descrição: [Descrição do bug]

──────────────────────────────────────────────────────────────
📋 ANÁLISE
──────────────────────────────────────────────────────────────

Comportamento atual:
[O que estava acontecendo]

Comportamento esperado:
[O que deveria acontecer]

Causa raiz:
[Por que o bug ocorreu]

──────────────────────────────────────────────────────────────
🔴 TESTE ESCRITO (VERMELHO)
──────────────────────────────────────────────────────────────

Arquivo: tests/test_xxx.py
Teste: test_should_xxx_when_yyy

```python
def test_should_xxx_when_yyy(self):
    # ... código do teste
```

Resultado inicial: ❌ FAIL
Mensagem: AssertionError: expected X but got Y

──────────────────────────────────────────────────────────────
🟢 CORREÇÃO (VERDE)
──────────────────────────────────────────────────────────────

Arquivo modificado: src/module/file.py
Linhas: 45-52

```python
# Antes
def problematic_function():
    # código com bug

# Depois
def problematic_function():
    # código corrigido
```

Resultado após correção: ✅ PASS

──────────────────────────────────────────────────────────────
♻️ REFATORAÇÃO
──────────────────────────────────────────────────────────────

- [x] Código simplificado
- [x] Variável renomeada para clareza
- [x] Duplicação removida

──────────────────────────────────────────────────────────────
✅ TESTES
──────────────────────────────────────────────────────────────

| Teste | Status |
|------|--------|
| test_should_xxx_when_yyy (novo) | ✅ |
| test_existing_1 | ✅ |
| test_existing_2 | ✅ |
| ... | ✅ |

Total: XX testes, 0 falhas

──────────────────────────────────────────────────────────────
📝 COMMIT
──────────────────────────────────────────────────────────────

```
fix(module): descrição curta (#XXX)

- Adicionar teste de regressão
- Corrigir causa raiz
- Adicionar testes de casos extremos

Fixes #XXX
```

──────────────────────────────────────────────────────────────
🎯 AÇÕES PÓS-CORREÇÃO
──────────────────────────────────────────────────────────────

- [ ] PR criado
- [ ] Code review solicitado
- [ ] Documentação atualizada
- [ ] Ticket fechado
```

## Próximo passo

```
╔══════════════════════════════════════════════════════════╗
║                    PRÓXIMO PASSO                         ║
╠══════════════════════════════════════════════════════════╣
║                                                          ║
║  → /qa:recette                                           ║
║    Re-testar após as correções                           ║
║                                                          ║
║  Veja também:                                            ║
║  • /common:pre-commit-check — Validar antes do commit    ║
║                                                          ║
╚══════════════════════════════════════════════════════════╝
```
