Test Framework

Relevant source files

• charges_parse_test.go
• examples_test.go
• invoice_test.go
• lines_parse_test.go
• ordering_parse_test.go
• ordering_test.go
• party_parse_test.go
• party_test.go

This document describes the testing infrastructure for the gobl.ubl conversion library, including test structure, helper functions, XSD validation, and golden file management. For information about example documents used in tests, see Example Documents.

Test Organization

The test framework is organized around two primary conversion directions, with dedicated test data directories for each:

Sources: examples_test.go279-305

Main Test Functions

The test suite includes two primary test functions that verify bidirectional conversion:

TestConvertToInvoice

Tests GOBL→UBL conversion by processing all JSON files in test/data/convert/:

Function	Location	Purpose
TestConvertToInvoice	examples_test.go38-77	Iterates through JSON examples, converts to UBL, validates against XSD
testInvoiceFrom	examples_test.go148-154	Loads GOBL envelope and converts to UBL Invoice
loadTestEnvelope	examples_test.go192-222	Reads and validates GOBL JSON file

The test performs the following steps:

Sources: examples_test.go38-77 examples_test.go148-154 examples_test.go192-222

TestParseInvoice

Tests UBL→GOBL parsing by processing all XML files in test/data/parse/:

Function	Location	Purpose
TestParseInvoice	examples_test.go79-145	Iterates through XML examples, converts to GOBL, compares output
testParseInvoice	examples_test.go173-189	Parses UBL XML and converts to GOBL envelope
testLoadXML	examples_test.go157-169	Loads raw XML data from file

The parsing flow follows this sequence:

Sources: examples_test.go79-145 examples_test.go173-189 examples_test.go157-169

XSD Schema Validation

The test framework validates generated UBL XML against official XSD schemas to ensure compliance with UBL 2.1 specifications:

ValidateXML Function

Located at examples_test.go264-277 this function uses libxml2 to perform XSD validation:

The validation process:

1. Parse XML bytes into libxml2 document
2. Validate document against loaded XSD schema
3. Extract first error if validation fails
4. Return nil if validation succeeds

Schema Loading

Schema files are loaded once per test run using loadSchema:

Schema File	Document Type	Location
UBL-Invoice-2.1.xsd	Invoice	examples_test.go29
UBL-CreditNote-2.1.xsd	CreditNote	examples_test.go30

Schemas are loaded from examples_test.go283-285:

test/data/schema/maindoc/UBL-Invoice-2.1.xsd
test/data/schema/maindoc/UBL-CreditNote-2.1.xsd

Sources: examples_test.go257-277 examples_test.go283-285

Golden File Management

The test framework uses a golden file approach where expected outputs are stored and compared against actual conversion results:

Update Flag

The --update flag at examples_test.go36 enables automatic regeneration of golden files:

When enabled, the flag triggers:

1. For GOBL→UBL tests: Write generated XML to test/data/convert/out/ and validate against XSD
2. For UBL→GOBL tests: Write generated JSON to test/data/parse/out/

File Writing Logic

The writeEnvelope function at examples_test.go234-245 conditionally writes files:

Sources: examples_test.go36 examples_test.go234-245

Static UUID for Deterministic Testing

To ensure reproducible test outputs, the framework uses a static UUID defined at examples_test.go32:

staticUUID = "0195ce71-dc9c-72c8-bf2c-9890a4a9f0a2"

This UUID is applied in two places:

1. GOBL Envelope: examples_test.go205 sets env.Head.UUID
2. Invoice Document: examples_test.go206-208 sets inv.UUID

Before final output, env.Calculate() is called to recalculate the digest with the static UUID, ensuring:

• Consistent output across test runs
• Predictable diff comparison
• Reliable golden file matching

Sources: examples_test.go32 examples_test.go205-212

Component-Specific Tests

Beyond the main conversion tests, component-specific test files verify individual conversion functions:

Line Item Tests

Located in lines_parse_test.go these tests verify:

Test Case	File	Focus
TestParseLines/ubl-example1.xml	lines_parse_test.go19-46	Basic line parsing, quantity, price, taxes
TestParseLines/ubl-example2.xml	lines_parse_test.go49-102	Line charges/discounts, item identities, metadata
TestParseLines/partial-invoice.xml	lines_parse_test.go105-123	OrderLineReference parsing
TestParseLines/BaseQuantity	lines_parse_test.go126-161	BaseQuantity price division

Sources: lines_parse_test.go1-162

Charges and Discounts Tests

Located in charges_parse_test.go these tests verify:

Test Case	File	Focus
TestParseCharges/ubl-example2.xml	charges_parse_test.go16-49	Document-level charges/discounts, tax categories
TestParseCharges/ubl-example5.xml	charges_parse_test.go51-86	UNTDID extension codes for charges/allowances
TestParseCharges/Allowance-example.xml	charges_parse_test.go88-131	BaseAmount and percentage-based calculations
TestBaseAmountErrorHandling	charges_parse_test.go134-154	Error handling for invalid BaseAmount values

The error handling test demonstrates robustness by modifying valid XML and verifying proper error propagation:

Sources: charges_parse_test.go1-155

Test Execution

Running All Tests

Execute the complete test suite:

Running with Coverage

Generate coverage report:

Running Specific Tests

Run individual test functions:

Updating Golden Files

Regenerate expected output files:

This command will:

1. Run all conversions
2. Validate XML against XSD schemas
3. Write new golden files to test/data/*/out/
4. Use these files as the new baseline for comparison

Sources: README.md131-139

Test Utilities and Helpers

The framework provides several utility functions for test data management:

Path Resolution Functions

Function	Purpose	Returns
getDataPath	examples_test.go291-293	Base test data directory
getConversionTypePath	examples_test.go295-300	Conversion-specific directory (convert/parse)
getOutPath	examples_test.go287-289	Output directory for golden files
getSchemaPath	examples_test.go283-285	XSD schema directory
getRootFolder	examples_test.go307-314	Repository root by finding go.mod

File Loading Functions

Function	Purpose	Location
loadOutputFile	Load golden file for comparison	examples_test.go224-232
getDataGlob	Get all files matching pattern	examples_test.go279-281
outputFilepath	Determine output path for file	examples_test.go247-255

Sources: examples_test.go224-332

Validation and Assertions

The test framework uses testify for assertions, providing clear failure messages:

Common Assertion Patterns

Pattern	Usage	Example
require.NoError	Critical errors that stop test	lines_parse_test.go21
assert.NoError	Non-critical errors	examples_test.go73
assert.Equal	Value comparison	lines_parse_test.go32
assert.Len	Collection size	lines_parse_test.go29
assert.NotNil	Nil checks	lines_parse_test.go27
assert.JSONEq	JSON comparison ignoring whitespace	examples_test.go142

Type Assertion Pattern

A common pattern for safely extracting types:

Sources: lines_parse_test.go23-24 charges_parse_test.go20-21

Roundtrip Testing Approach

While not explicitly implemented as a separate test, the framework supports roundtrip verification through sequential application of conversion and parsing tests:

The equivalence is verified through:

1. Static UUIDs ensure consistent identifiers
2. Calculate() ensures consistent digests
3. JSON comparison ignores whitespace via assert.JSONEq

Sources: examples_test.go106-114