Examples and Testing

Relevant source files

• examples_test.go
• ordering_test.go
• party_test.go

This page documents the comprehensive testing infrastructure and example documents provided with the gobl.ubl library. The test suite validates bidirectional conversion between GOBL and UBL formats across multiple contexts (EN16931, Peppol, XRechnung, French CIUS) and provides example documents for common invoice scenarios.

For information about the core conversion functions being tested, see Core API Functions. For details on the context system used in testing, see Context and Profile System.

Purpose and Scope

The testing framework serves three primary purposes:

1. Validation: Ensures bidirectional conversion between GOBL and UBL formats produces correct output
2. Documentation: Example documents demonstrate various invoice scenarios and regional variations
3. Regression Prevention: Golden file testing detects unintended changes in conversion output

The test infrastructure is located in examples_test.go1-433 and uses the testify assertion library along with optional Phive validation for XML compliance checking.

Test Framework Architecture

The testing system is organized around two main test functions that validate conversion in both directions, supported by helper functions for loading and processing test documents.

Test Framework Overview

Sources: examples_test.go42-122 examples_test.go124-220

Test Data Organization

The test data is organized in a hierarchical directory structure under test/data/ with separate folders for conversion direction and context type:

Directory	Purpose	Format	Description
test/data/convert/	GOBL to UBL	Input: JSON	Source GOBL envelopes for conversion testing
test/data/convert/{context}/out/	GOBL to UBL	Output: XML	Expected UBL output files (golden files)
test/data/parse/	UBL to GOBL	Input: XML	Source UBL documents for parsing testing
test/data/parse/{context}/out/	UBL to GOBL	Output: JSON	Expected GOBL output files (golden files)

Each context directory (en16931, peppol, peppol-self-billed, xrechnung, france-cius, france-extended) contains example documents specific to that UBL profile.

Sources: examples_test.go383-404

Conversion Testing (GOBL to UBL)

The TestConvertToInvoice function validates the GOBL to UBL conversion path across all supported contexts.

Test Execution Flow

GOBL to UBL Test Flow

Sources: examples_test.go42-122

Test Configuration

The test function defines six context configurations:

Each context has its own test subdirectory and is tested independently using nested t.Run() calls for clear test output organization.

Sources: examples_test.go56-68

UUID Normalization

To ensure consistent test output, the test framework replaces document UUIDs with a static value:

This normalization occurs in the loadTestEnvelopeFromPath function and affects both the envelope's head UUID and the invoice's document UUID.

Sources: examples_test.go33 examples_test.go258-261

Parsing Testing (UBL to GOBL)

The TestParseInvoice function validates the UBL to GOBL conversion path, parsing XML documents and comparing the resulting GOBL invoices against golden files.

Parsing Flow

The parsing test follows this sequence:

1. Load UBL XML from test/data/parse/{context}/*.xml
2. Call ubl.Parse() to deserialize XML into intermediate UBL structures
3. Call Invoice.Convert() to transform UBL to GOBL envelope
4. Normalize UUIDs to static values
5. Recalculate envelope to ensure consistent digests
6. Compare resulting invoice against golden file

Sources: examples_test.go124-220

Known Validation Issues

The parsing tests include an important comment about validation:

This indicates that the test suite uses real-world UBL examples that may not fully comply with GOBL's stricter validation rules, reflecting the reality that UBL documents in the wild often contain minor compliance issues.

Sources: examples_test.go164-168

Invoice Extraction and Comparison

The test extracts only the invoice portion from the envelope for comparison, ignoring envelope-level metadata differences:

Invoice-Level Comparison Strategy

Sources: examples_test.go192-215

Example Documents

The test suite includes several example document types demonstrating various invoice scenarios:

Example File	Type	Notable Features
invoice-minimal.json	Standard Invoice	Minimal required fields, credit transfer payment
invoice-complete.json	Standard Invoice	All optional fields populated, endpoint IDs
invoice-with-line-order.json	Standard Invoice	Line-level order references, delivery details
invoice-without-buyers-tax-id.json	Standard Invoice	Missing customer tax ID (edge case)
correction-invoice.json	Corrective Invoice	Preceding document references, type 384
credit-note.json	Credit Note	Negative amounts, credit note type

Each example is available in GOBL JSON format and can be converted to UBL XML in any supported context.

Sources: test/data/convert/invoice-minimal.json1-138 test/data/convert/invoice-with-line-order.json1-178 test/data/convert/invoice-without-buyers-tax-id.json1-179 test/data/convert/correction-invoice.json1-149

Test Helper Functions

The test framework provides several utility functions to simplify test implementation:

Document Loading Functions

Test Helper Function Hierarchy

Sources: examples_test.go222-352 examples_test.go383-432

Key Helper Functions

testInvoiceFrom(name string)

• Loads a GOBL envelope and converts to UBL Invoice using Peppol context
• Used for basic conversion tests
• Sources: examples_test.go222-229

testInvoiceFromContext(name string, ctx ubl.Context)

• Loads a GOBL envelope and converts using specified context
• Allows testing context-specific behavior
• Sources: examples_test.go231-238

loadTestEnvelopeFromPath(path string)

• Loads GOBL envelope from absolute file path
• Normalizes UUIDs to static value
• Recalculates envelope to ensure consistency
• Validates envelope before returning
• Optionally updates source file if --update flag is set
• Sources: examples_test.go240-283

testParseInvoice(name string)

• Loads UBL XML and converts to GOBL envelope
• Used for parsing validation tests
• Sources: examples_test.go301-319

testLoadXML(name string)

• Returns raw XML bytes from parse directory
• Handles subdirectories in name parameter
• Sources: examples_test.go285-299

Phive Validation Integration

The test framework includes optional integration with Phive, a validation service for UBL documents. When enabled via the --validate flag, each generated XML document is validated against its VESID (Validation Execution Set ID).

Validation Configuration

Phive Validation Flow

Sources: examples_test.go39-54 examples_test.go96-113

VESID Determination

The test determines the appropriate VESID based on the document type (Invoice vs CreditNote) and the context's VESID configuration. Each context defines VESIDs for both document types:

The validation results are logged as JSON if validation fails, providing detailed error information for debugging.

Sources: examples_test.go103-112

Update Mechanism

The test framework includes an update mechanism to regenerate golden files when conversion logic changes intentionally.

Update Flag Usage

The --update flag is defined as a boolean flag variable:

Sources: examples_test.go37

Update Behavior

When --update is enabled:

1. Input files: GOBL envelopes are normalized and rewritten with static UUIDs and recalculated digests
2. Output files: Generated UBL XML or parsed GOBL JSON is written to the out/ subdirectories
3. Validation: Tests still run assertions after updating, ensuring updates produce valid output

The update mechanism is used in three locations:

• loadTestEnvelopeFromPath: Updates source GOBL files examples_test.go272-280
• TestConvertToInvoice: Updates UBL XML output examples_test.go91-94
• TestParseInvoice: Updates parsed GOBL JSON output examples_test.go181-189

Component-Specific Tests

In addition to the comprehensive example tests, the library includes focused tests for specific components:

Party Testing

The party_test.go file validates party conversion details:

This test verifies that party endpoint IDs are correctly converted from GOBL to UBL format.

Sources: party_test.go1-20

Ordering Testing

The ordering_test.go file validates ordering reference conversion:

This test confirms that when no ordering information is present, the library generates a default "NA" order reference as required by some UBL profiles.

Sources: ordering_test.go1-21

XML Schema Validation Utility

The test framework includes a legacy XML validation function using libxml2:

This function is currently unused but provides XSD validation capabilities if needed. The Phive integration is the preferred validation method.

Sources: examples_test.go368-381