Estratégia de Testes

Visão Geral

O fiscal-rs possui 739+ testes distribuídos em 16 arquivos de teste, além de 5 alvos de fuzzing. A maioria dos testes foi portada diretamente das suítes PHP (sped-nfe) e TypeScript do FinOpenPOS, garantindo paridade funcional entre as implementações.

Contribuição upstream ao sped-nfe

Durante o desenvolvimento do fiscal-rs, não apenas portamos os testes existentes — contribuímos 370 novos testes de volta ao sped-nfe original via PR #1313 (mergeado), elevando a cobertura de 40% para 86,5% (de 216 para 586 testes, de 896 para 2.274 assertions).

Os 5 arquivos contribuídos:

Esse processo revelou bugs latentes no sped-nfe que existiam há anos e foram corrigidos no caminho. Não é só paridade — é evolução mútua.

Categorias de Teste

Testes Portados

A maior parte da suíte (492 testes) foi portada linha a linha de implementações existentes em PHP e TypeScript. Cada bloco describe()/it() do TypeScript se tornou um mod/#[test] em Rust.

Testes de Domínio

Testes escritos nativamente em Rust cobrindo módulos específicos:

• tax_icms_test.rs (19 testes) -- Todos os CSTs de ICMS (00, 10, 20, 30, 40/41/50, 51, 60, 70, 90), CSOSNs do Simples Nacional (101, 102, 103, 201, 202, 500, 900) e ICMS interestadual (UF destino). Utiliza rstest para parametrização.
• tax_pis_cofins_ipi_test.rs (17 testes) -- PIS, COFINS, IPI e Imposto de Importação
• xml_builder_test.rs (21 testes) -- Construção de XML NF-e/NFC-e com o InvoiceBuilder
• certificate_test.rs (14 testes) -- Extração de certificados PFX e assinatura digital XML
• complement_test.rs (8 testes) -- Anexação de protocolo SEFAZ e inutilização
• qrcode_test.rs (5 testes) -- Geração de QR codes v2.00 e v3.00

Snapshot Tests (insta)

Os 50 testes de snapshot utilizam a crate insta para verificar regressão de saída. Cobrem:

• XML utils -- tag(), escape_xml(), extract_xml_tag_value()
• Serialização de TaxElement -- ICMS00, PISAliq, COFINSAliq, IPITrib, II, ICMSUFDest
• Formatação monetária -- format_cents, format_rate, format_rate4
• Códigos de estado -- Mapeamento UF/IBGE para todos os 27 estados
• Totais de ICMS -- create_icms_totals, merge_icms_totals

Os snapshots ficam armazenados em tests/snapshots/ e são comparados automaticamente. Para atualizar:

# Revisar mudanças de snapshot interativamente
cargo insta review

# Aceitar todas as mudanças de uma vez
cargo insta accept

A crate suporta dois modos de asserção:

// Snapshot armazenada em arquivo (tests/snapshots/)
assert_snapshot!(tag("xNome", &[], "Test Company".into()));

// Snapshot inline (valor esperado no próprio código)
assert_snapshot!(format_cents_2(1050), @"10.50");

Property Tests (proptest)

Os 41 testes de propriedade utilizam proptest para verificar invariantes com entradas geradas aleatoriamente. Organizados em 5 blocos proptest!:

Exemplo de estratégia de geração:

fn reasonable_cents() -> impl Strategy<Value = i64> {
    -999_999_999i64..=999_999_999i64
}

fn safe_string() -> impl Strategy<Value = String> {
    "[a-zA-Z0-9 ]{1,50}"
}

Fuzz Targets (cargo-fuzz)

Os 5 alvos de fuzzing em fuzz/fuzz_targets/ testam a robustez contra entradas arbitrárias e potencialmente maliciosas:

# Executar fuzzing (requer nightly)
cargo +nightly fuzz run fuzz_xml_tag_extraction

# Executar por tempo limitado (60 segundos)
cargo +nightly fuzz run fuzz_gtin_validation -- -max_total_time=60

Infraestrutura de Testes

Módulo Comum (tests/common/mod.rs)

Todos os testes de integração compartilham helpers via mod common;:

// Helpers de asserção XML
expect_xml_tag_values(xml, &[("tag", "valor")]);
expect_xml_contains(xml, &["substring1", "substring2"]);
expect_xml_not_contains(xml, &["não-deve-existir"]);
expect_wrapped_in(xml, "tagWrapper");

// Fábricas de dados
sample_issuer()        // Emitente Simples Nacional
sample_issuer_normal() // Emitente Regime Normal
sample_recipient()     // Destinatário CPF
sample_item()          // Item com ICMS/PIS/COFINS
sample_payment()       // Pagamento em dinheiro R$20,00
sample_invoice_builder() // NFC-e em homologação

O sample_invoice_builder() retorna um InvoiceBuilder pré-configurado com emitente, item e pagamento no estado Draft, pronto para .build().

Fixtures (tests/fixtures/)

Arquivos de referência copiados das suítes de teste PHP:

O caminho para os fixtures é resolvido em tempo de compilação:

pub const FIXTURES_PATH: &str =
    concat!(env!("CARGO_MANIFEST_DIR"), "/tests/fixtures/");

Crates de Teste

O projeto utiliza as seguintes crates de teste:

Executando os Testes

Suíte Completa

# Com nextest (recomendado -- execução paralela)
cargo nextest run --all-features

# Com cargo test padrão
cargo test --all-features

Doc Tests

Doc tests não são capturados pelo nextest, então precisam ser executados separadamente:

cargo test --doc --all-features

Arquivo Individual

# Executar apenas os testes de ICMS
cargo nextest run --all-features -E 'test(tax_icms_test)'

# Executar apenas os snapshot tests
cargo nextest run --all-features -E 'test(snapshot_tests)'

# Executar apenas os property tests
cargo nextest run --all-features -E 'test(property_tests)'

Teste Específico

# Executar um teste pelo nome
cargo nextest run --all-features -E 'test(cst_00_regular_icms)'

# Com cargo test
cargo test --all-features cst_00_regular_icms

Fuzzing

# Instalar cargo-fuzz (requer nightly)
rustup install nightly
cargo install cargo-fuzz

# Listar alvos
cargo +nightly fuzz list

# Executar alvo específico
cargo +nightly fuzz run fuzz_xml_tag_extraction

Padrões de Teste

Testes Portados com XML Inline

Os testes portados frequentemente declaram XML de referência como constantes e verificam comportamento contra ele:

const NFE_REQUEST: &str = r##"<NFe xmlns="...">
    <infNFe versao="4.00" Id="NFe4321...">
        ...
    </infNFe>
</NFe>"##;

#[test]
fn test_to_authorize_nfe_valid() {
    let protocoled = attach_protocol(NFE_REQUEST, RESPONSE)
        .expect("should succeed");
    assert!(protocoled.contains("143220000009921"));
}

Testes Parametrizados com rstest

O rstest permite testar múltiplas variantes do mesmo cenário sem duplicação:

#[rstest]
#[case("40", "<ICMS40>", "<CST>40</CST>")]
#[case("41", "<ICMS40>", "<CST>41</CST>")]
#[case("50", "<ICMS40>", "<CST>50</CST>")]
fn cst_40_41_50_exempt_variants(
    #[case] cst: &str,
    #[case] expected_tag: &str,
    #[case] expected_cst: &str,
) {
    // ... mesmo corpo para as 3 variantes
}

Snapshot Tests com Inline Values

Para valores pequenos e estáveis, o insta suporta asserções inline:

#[test]
fn snapshot_format_cents_1050() {
    assert_snapshot!(format_cents_2(1050), @"10.50");
}

Se o valor mudar, o teste falha e cargo insta review permite revisar e aceitar a mudança.

Property Tests com Invariantes

Os testes de propriedade verificam que invariantes são mantidas para qualquer entrada gerada:

proptest! {
    #[test]
    fn escape_xml_never_contains_raw_special_chars(
        input in "\\PC{1,100}"
    ) {
        let escaped = escape_xml(&input);
        // Nenhum '<', '>', '"' ou '\'' pode aparecer cru
        // '&' só pode aparecer como parte de entidade XML
    }
}