Testing Framework

Relevant source files

• cfdi_test.go
• examples_test.go
• test/test.go

Purpose and Scope

The Testing Framework provides comprehensive validation infrastructure for the gobl.cfdi package, ensuring correct GOBL to CFDI XML conversion and bidirectional parsing. This framework includes test utilities, fixture management, XSD schema validation, and automated test execution patterns.

This page covers the overall testing infrastructure and organization. For detailed documentation of specific helper functions, see Test Utilities. For coverage of individual test scenarios and validation approaches, see Unit and Integration Tests. For information about test fixtures and XSD validation setup, see Test Data and Examples.

---

Testing Architecture Overview

The testing framework consists of three primary layers: test utilities that simplify test setup, unit tests that validate component behavior, and integration tests that verify end-to-end conversion and parsing workflows with XSD validation.

Testing Infrastructure Components

Sources: test/test.go1-154 cfdi_test.go1-127 examples_test.go1-196

---

Test Package Organization

The testing infrastructure is organized into distinct packages and file types, each serving a specific role in the validation workflow.

Component	Location	Purpose
Test Utilities	test/test.go	Helper functions for loading fixtures and creating test documents
Unit Tests	cfdi_test.go	Component-level validation of conversion logic
Integration Tests	examples_test.go	End-to-end conversion and parsing with XSD validation
GOBL Fixtures	test/data/convert/in/*.json	Input GOBL invoice envelopes for conversion tests
CFDI Fixtures	test/data/convert/out/*.xml	Expected CFDI XML output for conversion tests
Parse Fixtures	test/data/parse/in/*.xml	Input CFDI XML files for parsing tests
Parse Output	test/data/parse/out/*.json	Expected GOBL JSON from parsing tests
XSD Schemas	test/schema/schema.xsd	CFDI 4.0 XSD schemas for XML validation

Sources: test/test.go1-16 examples_test.go24-29

---

Test Utilities Package

The test package provides a set of helper functions that abstract common test setup patterns, reducing boilerplate and ensuring consistent test data handling across the test suite.

Test Utility Functions and Dependencies

Core Helper Functions

The test package exposes four primary functions for test setup:

Function	Input	Output	Purpose
NewDocumentFrom(name)	Fixture filename	*cfdi.Document	Load GOBL JSON and convert to CFDI Document
LoadTestInvoice(name)	Fixture filename	*bill.Invoice	Load GOBL invoice from fixture file
GenerateCFDIFrom(inv)	*bill.Invoice	*cfdi.Document	Convert invoice to CFDI without using fixtures
LoadParsedInvoice(filename)	CFDI XML filename	*bill.Invoice	Parse CFDI XML and return GOBL invoice

All functions automatically handle GOBL envelope calculation and validation, ensuring test data is in a consistent state. The LoadTestEnvelope function (test/test.go37-75) is the core helper that loads JSON files, parses them with gobl.Parse, creates envelopes if needed, and runs Calculate() and Validate() operations.

Sources: test/test.go16-89 test/test.go91-115

---

Test Execution Flow

The testing framework supports two primary execution modes: standard test runs that compare outputs against fixtures, and update mode that regenerates expected fixtures from current code behavior.

Test Execution Modes and Workflows

The --update flag (examples_test.go32) controls whether tests compare against existing fixtures (standard mode) or regenerate fixtures from current code behavior (update mode). In update mode, XSD validation occurs before writing files to ensure only valid CFDI XML is saved as expected output.

Sources: examples_test.go37-73 examples_test.go75-113 cfdi_test.go15-84

---

Test Data Directory Structure

Test fixtures are organized into separate directories based on operation type (convert vs parse) and direction (input vs output), enabling clear separation of test concerns and parallel test execution.

Test Data Organization and File Paths

The directory structure follows a consistent pattern where each operation type has in/ and out/ subdirectories. The LoadTestEnvelope function (test/test.go38-42) includes backward compatibility support for legacy fixtures stored directly in test/data/ without the subdirectory structure.

Path Pattern	Content Type	Usage
test/data/convert/in/*.json	GOBL invoice envelopes	Source data for conversion tests
test/data/convert/out/*.xml	CFDI XML documents	Expected conversion output
test/data/parse/in/*.xml	CFDI XML documents	Source data for parsing tests
test/data/parse/out/*.json	GOBL invoice envelopes	Expected parsing output
test/schema/schema.xsd	XSD schema definitions	XML validation rules

Sources: test/test.go38-43 examples_test.go24-29 examples_test.go152-181

---

XSD Schema Validation

Integration tests validate generated CFDI XML against official SAT XSD schemas to ensure compliance with Mexican tax authority requirements. The validation process uses the libxml2 library with XSD parsing capabilities.

XSD Validation Pipeline

The loadSchema function (examples_test.go115-123) loads the CFDI 4.0 XSD schema from test/schema/schema.xsd. The validateDoc function (examples_test.go183-195) parses the XML document with libxml2 and validates it against the schema, returning a list of validation errors. During update mode execution, any validation errors cause the test to fail and prevent invalid XML from being written to fixture files.

The validation process ensures:

• XML structure matches CFDI 4.0 schema requirements
• All required attributes and elements are present
• Data types and formats comply with SAT specifications
• Namespace declarations are correct

Sources: examples_test.go115-123 examples_test.go183-195 examples_test.go54-66

---

Unit Test Patterns

Unit tests in cfdi_test.go validate specific conversion behaviors and edge cases using the test utilities package. Tests focus on individual document components and their transformations from GOBL to CFDI structures.

Common Test Patterns

Document Field Validation

Tests like TestComprobanteIngreso (cfdi_test.go15-42) load fixtures using test.NewDocumentFrom and assert individual field values match expected CFDI requirements:

doc, err := test.NewDocumentFrom("invoice-b2b-full.json")
require.NoError(t, err)
assert.Equal(t, "I", doc.TipoDeComprobante)
assert.Equal(t, "LMC", doc.Serie)
assert.Equal(t, "0010", doc.Folio)

Dynamic Invoice Modification

Tests can load invoices with test.LoadTestInvoice, modify them, then generate CFDI documents using test.GenerateCFDIFrom (cfdi_test.go44-83):

inv, _ := test.LoadTestInvoice("invoice-b2b-full.json")
inv.Payment.Advances = nil
doc, _ := test.GenerateCFDIFrom(inv)
assert.Equal(t, "PPD", doc.MetodoPago)

This pattern enables testing of conditional logic based on invoice state without creating separate fixture files for each variation.

Complement and Extension Validation

Tests verify optional document features are correctly present or absent:

assert.Nil(t, doc.ComplementoTimbreFiscalDigital)
assert.Nil(t, doc.ComplementoValesDeDespensa)
assert.Nil(t, doc.ComplementoEstadoCuentaCombustible)

Sources: cfdi_test.go15-126 test/test.go16-89

---

Integration Test Patterns

Integration tests in examples_test.go provide comprehensive validation by testing the entire conversion and parsing pipeline against fixture files, with automatic XSD validation in update mode.

Conversion Tests

The TestConvertExamples function (examples_test.go37-73) iterates through all JSON fixtures in test/data/convert/in/, converts them to CFDI XML, and compares output against expected XML files:

1. Load XSD schema using loadSchema()
2. Find all *.json files in convert input directory
3. For each fixture:
   • Load GOBL envelope with loadEnvelope()
   • Convert to CFDI with cfdi.Convert()
   • Serialize to XML bytes with doc.Bytes()
   • In update mode: validate against XSD and write to output
   • In standard mode: compare against existing output fixture

Parsing Tests

The TestParseExamples function (examples_test.go75-113) validates bidirectional conversion by parsing CFDI XML back to GOBL:

1. Find all *.xml files in parse input directory
2. For each fixture:
   • Parse CFDI XML with cfdi.Parse()
   • Set static UUID to ensure consistent output
   • Calculate envelope totals
   • Add mock signature for stamp validation
   • Write envelope to output (in update mode)
   • Compare JSON against expected output fixture

The static UUID assignment (examples_test.go34 examples_test.go88-92) ensures test stability across executions by preventing UUID randomness from causing false test failures.

Sources: examples_test.go37-113 examples_test.go125-139 examples_test.go141-150

---

Testing Dependencies

The testing framework integrates with multiple external libraries and internal packages to provide comprehensive validation capabilities.

Dependency	Import Path	Usage
testify/assert	github.com/stretchr/testify/assert	Assertion functions for test validation
testify/require	github.com/stretchr/testify/require	Test requirement checks that halt on failure
libxml2	github.com/lestrrat-go/libxml2	XML parsing for XSD validation
libxml2/xsd	github.com/lestrrat-go/libxml2/xsd	XSD schema parsing and validation
gobl	github.com/invopop/gobl	Core GOBL envelope and parsing operations
gobl/bill	github.com/invopop/gobl/bill	Invoice structures and types
gobl/dsig	github.com/invopop/gobl/dsig	Digital signature types for mock data
gobl/uuid	github.com/invopop/gobl/uuid	UUID types for test data consistency
gobl.cfdi	github.com/invopop/gobl.cfdi	Main conversion package under test
gobl.cfdi/test	github.com/invopop/gobl.cfdi/test	Test utilities package

The test suite uses flag.Bool (examples_test.go32) to support the --update flag for fixture regeneration, enabling developers to update expected outputs when conversion logic changes intentionally.

Sources: cfdi_test.go3-13 examples_test.go3-22 test/test.go4-14