einvoice/test

EInvoice Test Suite

test/
├── readme.md                              # This file
├── helpers/
│   ├── test-utils.ts                     # Common test utilities and factories
│   ├── corpus.loader.ts                  # Test corpus file management
│   └── performance.tracker.ts            # Performance measurement utilities
└── suite/
    ├── einvoice_format-detection/        # Format detection tests (FD)
    ├── einvoice_validation/              # Validation tests (VAL)
    ├── einvoice_pdf-operations/          # PDF operations tests (PDF)
    ├── einvoice_conversion/              # Format conversion tests (CONV)
    ├── einvoice_parsing/                 # XML parsing tests (PARSE)
    ├── einvoice_encoding/                # XML encoding tests (ENC)
    ├── einvoice_error-handling/          # Error handling tests (ERR)
    ├── einvoice_performance/             # Performance tests (PERF)
    ├── einvoice_security/                # Security tests (SEC)
    ├── einvoice_edge-cases/              # Edge case tests (EDGE)
    ├── einvoice_standards-compliance/    # Standards compliance tests (STD)
    └── einvoice_corpus-validation/       # Corpus validation tests (CORP)

Test ID Convention

All test files follow a strict naming convention: test.<category-id>.<description>.ts

Examples:

• test.fd-01.ubl-detection.ts - UBL format detection test
• test.val-01.en16931-business-rules.ts - EN16931 business rules validation test
• test.pdf-01.xml-extraction.ts - PDF XML extraction test

Test Corpus Overview

Our test suite leverages an extensive corpus of 646+ real-world invoice files:

Format	Files	Description
CII XML-Rechnung	28	German Cross-Industry Invoice samples
UBL XML-Rechnung	28	German UBL format samples
ZUGFeRD v1	24	German hybrid PDF/XML v1 samples
ZUGFeRD v2/Factur-X	97	German/French hybrid PDF/XML v2 samples
PEPPOL	2	Large Pan-European invoice samples
FatturaPA	15	Italian electronic invoice samples
EN16931 Test Cases	309	Official validation test files
EDIFACT	20	Legacy EDI format samples

Test Categories

1. Format Detection (FD)

Tests for validating automatic invoice format detection from XML and PDF files.

ID	Test Description	Priority	Implementation
FD-01	UBL Format Detection	High	suite/einvoice_format-detection/test.fd-01.ubl-detection.ts
FD-02	CII Format Detection	High	suite/einvoice_format-detection/test.fd-02.cii-detection.ts
FD-03	ZUGFeRD v1 Detection	High	suite/einvoice_format-detection/test.fd-03.zugferd-v1-detection.ts
FD-04	ZUGFeRD v2/Factur-X Detection	High	suite/einvoice_format-detection/test.fd-04.facturx-detection.ts
FD-05	XRechnung Detection	High	suite/einvoice_format-detection/test.fd-05.xrechnung-detection.ts
FD-06	FatturaPA Detection	Medium	suite/einvoice_format-detection/test.fd-06.fatturapa-detection.ts
FD-07	PEPPOL BIS Detection	Medium	suite/einvoice_format-detection/test.fd-07.peppol-detection.ts
FD-08	Unknown Format Handling	High	suite/einvoice_format-detection/test.fd-08.unknown-format.ts
FD-09	Format Detection from PDF	High	suite/einvoice_format-detection/test.fd-09.pdf-format-detection.ts
FD-10	Format Confidence Scoring	Medium	suite/einvoice_format-detection/test.fd-10.confidence-scoring.ts
FD-11	Large File Format Detection	Medium	suite/einvoice_format-detection/test.fd-11.large-file-detection.ts
FD-12	Streaming Format Detection	Low	suite/einvoice_format-detection/test.fd-12.streaming-detection.ts

2. Validation (VAL)

Tests for validating invoice content against various standards and business rules.

ID	Test Description	Priority	Implementation
VAL-01	EN16931 Business Rules (BR-*)	High	suite/einvoice_validation/test.val-01.en16931-business-rules.ts
VAL-02	EN16931 Codelist Validation (BR-CL-*)	High	suite/einvoice_validation/test.val-02.en16931-codelists.ts
VAL-03	EN16931 Calculation Rules (BR-CO-*)	High	suite/einvoice_validation/test.val-03.en16931-calculations.ts
VAL-04	XRechnung CIUS Validation	High	suite/einvoice_validation/test.val-04.xrechnung-cius.ts
VAL-05	ZUGFeRD Profile Validation	High	suite/einvoice_validation/test.val-05.zugferd-profiles.ts
VAL-06	FatturaPA Schema Validation	Medium	suite/einvoice_validation/test.val-06.fatturapa-schema.ts
VAL-07	PEPPOL BIS Validation	Medium	suite/einvoice_validation/test.val-07.peppol-bis.ts
VAL-08	Syntax Level Validation	High	suite/einvoice_validation/test.val-08.syntax-validation.ts
VAL-09	Semantic Level Validation	High	suite/einvoice_validation/test.val-09.semantic-validation.ts
VAL-10	Business Level Validation	High	suite/einvoice_validation/test.val-10.business-validation.ts
VAL-11	Custom Validation Rules	Low	suite/einvoice_validation/test.val-11.custom-rules.ts
VAL-12	Validation Performance	Medium	suite/einvoice_validation/test.val-12.validation-performance.ts
VAL-13	Validation Error Reporting	High	suite/einvoice_validation/test.val-13.error-reporting.ts
VAL-14	Multi-Format Validation	Medium	suite/einvoice_validation/test.val-14.multi-format.ts

3. PDF Operations (PDF)

Tests for PDF handling including extraction and embedding of XML invoice data.

ID	Test Description	Priority	Implementation
PDF-01	XML Extraction from PDF/A-3	High	suite/einvoice_pdf-operations/test.pdf-01.xml-extraction.ts
PDF-02	ZUGFeRD v1 Extraction	High	suite/einvoice_pdf-operations/test.pdf-02.zugferd-v1-extraction.ts
PDF-03	ZUGFeRD v2/Factur-X Extraction	High	suite/einvoice_pdf-operations/test.pdf-03.facturx-extraction.ts
PDF-04	XML Embedding into PDF	High	suite/einvoice_pdf-operations/test.pdf-04.xml-embedding.ts
PDF-05	PDF/A-3 Creation	High	suite/einvoice_pdf-operations/test.pdf-05.pdfa3-creation.ts
PDF-06	Multiple Attachment Handling	Medium	suite/einvoice_pdf-operations/test.pdf-06.multiple-attachments.ts
PDF-07	PDF Metadata Preservation	Medium	suite/einvoice_pdf-operations/test.pdf-07.metadata-preservation.ts
PDF-08	Large PDF Handling	Medium	suite/einvoice_pdf-operations/test.pdf-08.large-pdf-handling.ts
PDF-09	Corrupted PDF Recovery	High	suite/einvoice_pdf-operations/test.pdf-09.corrupted-pdf.ts
PDF-10	PDF Signature Validation	Medium	suite/einvoice_pdf-operations/test.pdf-10.signature-validation.ts
PDF-11	PDF Compression	Low	suite/einvoice_pdf-operations/test.pdf-11.compression.ts
PDF-12	Concurrent PDF Operations	Medium	suite/einvoice_pdf-operations/test.pdf-12.concurrent-operations.ts

4. Format Conversion (CONV)

Tests for converting between different electronic invoice formats.

ID	Test Description	Priority	Implementation
CONV-01	CII to UBL Conversion	High	suite/einvoice_conversion/test.conv-01.cii-to-ubl.ts
CONV-02	UBL to CII Conversion	High	suite/einvoice_conversion/test.conv-02.ubl-to-cii.ts
CONV-03	ZUGFeRD to XRechnung	High	suite/einvoice_conversion/test.conv-03.zugferd-to-xrechnung.ts
CONV-04	Factur-X to UBL	Medium	suite/einvoice_conversion/test.conv-04.facturx-to-ubl.ts
CONV-05	FatturaPA Conversion	Low	suite/einvoice_conversion/test.conv-05.fatturapa-conversion.ts
CONV-06	Data Loss Detection	High	suite/einvoice_conversion/test.conv-06.data-loss-detection.ts
CONV-07	Field Mapping Validation	High	suite/einvoice_conversion/test.conv-07.field-mapping.ts
CONV-08	Extension Preservation	Medium	suite/einvoice_conversion/test.conv-08.extension-preservation.ts
CONV-09	Round-Trip Conversion	High	suite/einvoice_conversion/test.conv-09.round-trip.ts
CONV-10	Batch Conversion	Medium	suite/einvoice_conversion/test.conv-10.batch-conversion.ts
CONV-11	Character Encoding	High	suite/einvoice_conversion/test.conv-11.character-encoding.ts
CONV-12	Conversion Performance	Medium	suite/einvoice_conversion/test.conv-12.performance.ts

5. XML Parsing (PARSE)

Tests for XML parsing capabilities and error recovery.

ID	Test Description	Priority	Implementation
PARSE-01	Well-Formed XML Parsing	High	suite/einvoice_parsing/test.parse-01.well-formed-xml.ts
PARSE-02	Malformed XML Recovery	High	suite/einvoice_parsing/test.parse-02.malformed-recovery.ts
PARSE-03	Character Encoding Detection	High	suite/einvoice_parsing/test.parse-03.encoding-detection.ts
PARSE-04	BOM Handling	Medium	suite/einvoice_parsing/test.parse-04.bom-handling.ts
PARSE-05	Namespace Resolution	High	suite/einvoice_parsing/test.parse-05.namespace-resolution.ts
PARSE-06	Large XML Streaming	Medium	suite/einvoice_parsing/test.parse-06.streaming-parse.ts
PARSE-07	XML Schema Validation	High	suite/einvoice_parsing/test.parse-07.schema-validation.ts
PARSE-08	XPath Evaluation	Medium	suite/einvoice_parsing/test.parse-08.xpath-evaluation.ts
PARSE-09	Entity Reference Resolution	Medium	suite/einvoice_parsing/test.parse-09.entity-references.ts
PARSE-10	CDATA Section Handling	Low	suite/einvoice_parsing/test.parse-10.cdata-sections.ts
PARSE-11	Processing Instructions	Low	suite/einvoice_parsing/test.parse-11.processing-instructions.ts
PARSE-12	Memory-Efficient Parsing	High	suite/einvoice_parsing/test.parse-12.memory-efficiency.ts

6. XML Encoding (ENC)

Tests for XML generation and encoding.

ID	Test Description	Priority	Implementation
ENC-01	UTF-8 Encoding	High	suite/einvoice_encoding/test.enc-01.utf8-encoding.ts
ENC-02	Special Character Escaping	High	suite/einvoice_encoding/test.enc-02.character-escaping.ts
ENC-03	Namespace Declaration	High	suite/einvoice_encoding/test.enc-03.namespace-declaration.ts
ENC-04	Pretty Printing	Low	suite/einvoice_encoding/test.enc-04.pretty-printing.ts
ENC-05	Compact Encoding	Low	suite/einvoice_encoding/test.enc-05.compact-encoding.ts
ENC-06	Line Length Limits	Medium	suite/einvoice_encoding/test.enc-06.line-length.ts
ENC-07	International Characters	High	suite/einvoice_encoding/test.enc-07.international-chars.ts
ENC-08	XML Declaration	Medium	suite/einvoice_encoding/test.enc-08.xml-declaration.ts
ENC-09	Attribute Ordering	Low	suite/einvoice_encoding/test.enc-09.attribute-ordering.ts
ENC-10	Empty Element Handling	Medium	suite/einvoice_encoding/test.enc-10.empty-elements.ts

7. Error Handling (ERR)

Tests for error handling and recovery mechanisms.

ID	Test Description	Priority	Implementation
ERR-01	Parsing Error Recovery	High	suite/einvoice_error-handling/test.err-01.parsing-recovery.ts
ERR-02	Validation Error Details	High	suite/einvoice_error-handling/test.err-02.validation-errors.ts
ERR-03	PDF Operation Errors	High	suite/einvoice_error-handling/test.err-03.pdf-errors.ts
ERR-04	Format Conversion Errors	High	suite/einvoice_error-handling/test.err-04.conversion-errors.ts
ERR-05	Error Context Information	Medium	suite/einvoice_error-handling/test.err-05.error-context.ts
ERR-06	Error Recovery Strategies	High	suite/einvoice_error-handling/test.err-06.recovery-strategies.ts
ERR-07	Error Serialization	Medium	suite/einvoice_error-handling/test.err-07.error-serialization.ts
ERR-08	Concurrent Error Handling	Medium	suite/einvoice_error-handling/test.err-08.concurrent-errors.ts
ERR-09	Error Metrics Collection	Low	suite/einvoice_error-handling/test.err-09.error-metrics.ts
ERR-10	Custom Error Classes	High	suite/einvoice_error-handling/test.err-10.custom-errors.ts

8. Performance (PERF)

Tests for performance characteristics and optimization.

ID	Test Description	Priority	Implementation
PERF-01	Format Detection Speed	High	suite/einvoice_performance/test.perf-01.detection-speed.ts
PERF-02	Validation Performance	High	suite/einvoice_performance/test.perf-02.validation-performance.ts
PERF-03	PDF Extraction Speed	High	suite/einvoice_performance/test.perf-03.pdf-extraction.ts
PERF-04	Conversion Throughput	Medium	suite/einvoice_performance/test.perf-04.conversion-throughput.ts
PERF-05	Memory Usage Profiling	High	suite/einvoice_performance/test.perf-05.memory-usage.ts
PERF-06	CPU Utilization	Medium	suite/einvoice_performance/test.perf-06.cpu-utilization.ts
PERF-07	Concurrent Processing	High	suite/einvoice_performance/test.perf-07.concurrent-processing.ts
PERF-08	Large File Processing	High	suite/einvoice_performance/test.perf-08.large-files.ts
PERF-09	Streaming Performance	Medium	suite/einvoice_performance/test.perf-09.streaming.ts
PERF-10	Cache Efficiency	Medium	suite/einvoice_performance/test.perf-10.cache-efficiency.ts
PERF-11	Batch Processing	High	suite/einvoice_performance/test.perf-11.batch-processing.ts
PERF-12	Resource Cleanup	High	suite/einvoice_performance/test.perf-12.resource-cleanup.ts

9. Security (SEC)

Tests for security features and vulnerability prevention.

ID	Test Description	Priority	Implementation
SEC-01	XML External Entity (XXE) Prevention	High	suite/einvoice_security/test.sec-01.xxe-prevention.ts
SEC-02	XML Bomb Prevention	High	suite/einvoice_security/test.sec-02.xml-bomb.ts
SEC-03	PDF Malware Detection	High	suite/einvoice_security/test.sec-03.pdf-malware.ts
SEC-04	Input Validation	High	suite/einvoice_security/test.sec-04.input-validation.ts
SEC-05	Path Traversal Prevention	High	suite/einvoice_security/test.sec-05.path-traversal.ts
SEC-06	Memory DoS Prevention	Medium	suite/einvoice_security/test.sec-06.memory-dos.ts
SEC-07	Schema Validation Security	Medium	suite/einvoice_security/test.sec-07.schema-security.ts
SEC-08	Cryptographic Signature Validation	High	suite/einvoice_security/test.sec-08.signature-validation.ts
SEC-09	Safe Error Messages	Medium	suite/einvoice_security/test.sec-09.safe-errors.ts
SEC-10	Resource Limits	High	suite/einvoice_security/test.sec-10.resource-limits.ts

10. Edge Cases (EDGE)

Tests for unusual scenarios and extreme conditions.

ID	Test Description	Priority	Implementation
EDGE-01	Empty Invoice Files	Medium	suite/einvoice_edge-cases/test.edge-01.empty-files.ts
EDGE-02	Gigabyte-Size Invoices	Low	suite/einvoice_edge-cases/test.edge-02.gigabyte-files.ts
EDGE-03	Deeply Nested XML Structures	Medium	suite/einvoice_edge-cases/test.edge-03.deep-nesting.ts
EDGE-04	Unusual Character Sets	Medium	suite/einvoice_edge-cases/test.edge-04.unusual-charsets.ts
EDGE-05	Zero-Byte PDFs	Low	suite/einvoice_edge-cases/test.edge-05.zero-byte-pdf.ts
EDGE-06	Circular References	Medium	suite/einvoice_edge-cases/test.edge-06.circular-references.ts
EDGE-07	Maximum Field Lengths	Medium	suite/einvoice_edge-cases/test.edge-07.max-field-lengths.ts
EDGE-08	Mixed Format Documents	Low	suite/einvoice_edge-cases/test.edge-08.mixed-formats.ts
EDGE-09	Corrupted ZIP Containers	Medium	suite/einvoice_edge-cases/test.edge-09.corrupted-zip.ts
EDGE-10	Time Zone Edge Cases	Low	suite/einvoice_edge-cases/test.edge-10.timezone-edges.ts

11. Standards Compliance (STD)

Tests for compliance with international e-invoicing standards.

ID	Test Description	Priority	Implementation
STD-01	EN16931 Core Compliance	High	suite/einvoice_standards-compliance/test.std-01.en16931-core.ts
STD-02	XRechnung CIUS Compliance	High	suite/einvoice_standards-compliance/test.std-02.xrechnung-cius.ts
STD-03	PEPPOL BIS 3.0 Compliance	High	suite/einvoice_standards-compliance/test.std-03.peppol-bis.ts
STD-04	ZUGFeRD 2.1 Compliance	High	suite/einvoice_standards-compliance/test.std-04.zugferd-21.ts
STD-05	Factur-X 1.0 Compliance	High	suite/einvoice_standards-compliance/test.std-05.facturx-10.ts
STD-06	FatturaPA 1.2 Compliance	Medium	suite/einvoice_standards-compliance/test.std-06.fatturapa-12.ts
STD-07	UBL 2.1 Compliance	High	suite/einvoice_standards-compliance/test.std-07.ubl-21.ts
STD-08	CII D16B Compliance	High	suite/einvoice_standards-compliance/test.std-08.cii-d16b.ts
STD-09	ISO 19005 PDF/A-3 Compliance	Medium	suite/einvoice_standards-compliance/test.std-09.pdfa3.ts
STD-10	Country-Specific Extensions	Medium	suite/einvoice_standards-compliance/test.std-10.country-extensions.ts

12. Corpus Validation (CORP)

Tests using the complete test corpus to ensure real-world compatibility.

ID	Test Description	Priority	Implementation
CORP-01	XML-Rechnung Corpus Processing	High	suite/einvoice_corpus-validation/test.corp-01.xml-rechnung.ts
CORP-02	ZUGFeRD v1 Corpus Processing	High	suite/einvoice_corpus-validation/test.corp-02.zugferd-v1.ts
CORP-03	ZUGFeRD v2 Corpus Processing	High	suite/einvoice_corpus-validation/test.corp-03.zugferd-v2.ts
CORP-04	PEPPOL Large Files Processing	High	suite/einvoice_corpus-validation/test.corp-04.peppol-large.ts
CORP-05	FatturaPA Corpus Processing	Medium	suite/einvoice_corpus-validation/test.corp-05.fatturapa.ts
CORP-06	EN16931 Test Suite Execution	High	suite/einvoice_corpus-validation/test.corp-06.en16931-suite.ts
CORP-07	Cross-Format Corpus Validation	Medium	suite/einvoice_corpus-validation/test.corp-07.cross-format.ts
CORP-08	Failed Invoice Handling	High	suite/einvoice_corpus-validation/test.corp-08.failed-invoices.ts
CORP-09	Corpus Statistics Generation	Low	suite/einvoice_corpus-validation/test.corp-09.statistics.ts
CORP-10	Regression Testing	High	suite/einvoice_corpus-validation/test.corp-10.regression.ts

Running Tests

Run All Tests

cd einvoice
pnpm test

Run Specific Test Category

# Run all format detection tests
pnpm test test/suite/einvoice_format-detection

# Run all validation tests
pnpm test test/suite/einvoice_validation

Run Single Test File

# Run UBL detection test
tsx test/suite/einvoice_format-detection/test.fd-01.ubl-detection.ts

# Run EN16931 business rules test
tsx test/suite/einvoice_validation/test.val-01.en16931-business-rules.ts

Run Tests with Coverage

# Generate coverage report
pnpm test --coverage

# Run specific category with coverage
pnpm test test/suite/einvoice_validation --coverage

Run Performance Tests Only

# Run all performance tests
pnpm test test/suite/einvoice_performance

# Run with performance profiling
pnpm test test/suite/einvoice_performance --profile

Performance Benchmarks

Expected performance metrics for production use:

Operation	Target	Acceptable	Maximum
Format Detection	<5ms	<10ms	50ms
XML Parsing (1MB)	<50ms	<100ms	500ms
Validation (Syntax)	<20ms	<50ms	200ms
Validation (Business)	<100ms	<200ms	1000ms
PDF Extraction	<200ms	<500ms	2000ms
Format Conversion	<100ms	<200ms	1000ms
Concurrent Operations	100/sec	50/sec	10/sec
Memory per Invoice	<50MB	<100MB	500MB

Security Requirements

All security tests must pass for production deployment:

• XML Security: No XXE vulnerabilities, no billion laughs attacks
• PDF Security: Malware detection, safe extraction
• Input Validation: All inputs sanitized and validated
• Resource Limits: Memory and CPU usage bounded
• Error Handling: No sensitive data in error messages
• Path Security: No directory traversal vulnerabilities

Production Readiness Criteria

Production Gate 1: Core Functionality (>95% tests passing)

• Format detection accuracy
• Basic parsing and validation
• Simple conversions
• Error handling

Production Gate 2: Standards Compliance (>90% tests passing)

• EN16931 compliance
• Major format support (UBL, CII, ZUGFeRD)
• Validation accuracy
• PDF operations

Production Gate 3: Enterprise Ready (>85% tests passing)

• Performance under load
• Security hardening
• Full format support
• Advanced features

Test Data Management

Corpus Organization

test/assets/corpus/
├── XML-Rechnung/        # German standard samples
├── ZUGFeRDv1/          # Legacy ZUGFeRD
├── ZUGFeRDv2/          # Current ZUGFeRD/Factur-X
├── PEPPOL/             # Pan-European samples
├── fatturaPA/          # Italian samples
├── incoming/           # User-submitted samples
└── synthetic/          # Generated test cases

Test Data Guidelines

1. Real-World Data: Use actual invoice samples where possible
2. Anonymization: Remove sensitive business data
3. Edge Cases: Include malformed and boundary cases
4. Version Coverage: Test multiple versions of each standard
5. Size Variety: From minimal to multi-megabyte invoices

Continuous Integration

CI Pipeline Stages

1. Quick Tests (<5 min): Format detection, basic validation
2. Standard Tests (<15 min): All unit tests, corpus validation
3. Extended Tests (<30 min): Performance, security, edge cases
4. Nightly Tests (<2 hours): Full corpus, stress tests, memory profiling

Test Reports

• Coverage reports published to coverage/
• Performance metrics tracked in benchmarks/
• Failing corpus files logged to test-results/failures/

Contributing Tests

Adding New Tests

1. Follow the naming convention: test.<category>-<number>.<description>.ts
2. Include clear test description and expected outcomes
3. Add to the appropriate category table in this README
4. Ensure the test uses the test utilities and corpus
5. Include performance measurements where applicable

Test Quality Guidelines

• Each test should be independent and idempotent
• Use descriptive test names and assertions
• Include both positive and negative test cases
• Document any special setup or requirements
• Clean up any generated files or resources

Test Utilities

Common Test Helpers

import { TestFileHelpers, TestInvoiceFactory, PerformanceUtils } from '../helpers/test-utils';

// Load test file from corpus
const invoice = await TestFileHelpers.loadTestFile('corpus/UBL/example.xml');

// Create test invoice
const testInvoice = TestInvoiceFactory.createMinimalInvoice();

// Measure performance
const { result, duration } = await PerformanceUtils.measure('operation', async () => {
  // ... operation to measure
});

Assertion Helpers

import { InvoiceAssertions } from '../helpers/test-utils';

// Assert required fields
InvoiceAssertions.assertRequiredFields(invoice);

// Assert format detection
InvoiceAssertions.assertFormatDetection(detected, expected, filePath);

// Assert validation result
InvoiceAssertions.assertValidationResult(result, expectedValid, filePath);

Known Issues and Limitations

Current Limitations

1. FatturaPA: Limited implementation, basic support only
2. EDIFACT: Read-only, no generation support
3. Large Files: Streaming not fully implemented for >100MB files
4. Signatures: Digital signature validation in development

Test Flakiness

• Network-dependent tests may fail in offline environments
• Performance tests may vary based on system load
• Some PDF tests require specific fonts installed

Future Test Enhancements

Planned Additions

1. AI-Powered Testing: Fuzzing with ML-generated invoices
2. Visual Regression: PDF rendering comparison
3. Internationalization: Full Unicode and RTL support testing
4. Blockchain Integration: Distributed ledger validation
5. Real-time Processing: Streaming and event-driven tests