Uniword uses RSpec for testing with a comprehensive suite of unit, integration, and round-trip tests.

1. Running Tests

1.1. All Tests 

bundle exec rspec

1.2. Specific Test Files 

bundle exec rspec spec/uniword/document_spec.rb

1.3. Test Categories

Run specific categories of tests:

# Unit tests
bundle exec rspec spec/uniword/

# Integration tests
bundle exec rspec spec/integration/

# Performance tests
bundle exec rspec spec/performance/

2. Test Structure

Tests use RSpec with let for shared variables. No mocks or stubs are used:

RSpec.describe MyClass do
  describe '#my_method' do
    context 'when condition is true' do
      it 'returns expected result' do
        # Test implementation
      end
    end

    context 'when condition is false' do
      it 'raises an error' do
        expect { subject.my_method }.to raise_error(ArgumentError)
      end
    end
  end
end

3. Test Categories

Unit tests

Test individual classes in isolation. Each model class has its own spec file.

Integration tests

Test component interactions such as document loading, saving, and format conversion.

Performance tests

Benchmark critical operations to catch regressions.

Round-trip tests

Verify format conversion fidelity by loading, saving, and comparing documents.

4. Test Coverage

The project aims for high test coverage. New features should include comprehensive tests covering:

  • Happy path scenarios

  • Edge cases

  • Error conditions

  • Round-trip conversions

5. Testing Guidelines

  • Each test should focus on a single behavior

  • Follow MECE (Mutually Exclusive, Collectively Exhaustive) principles

  • Use let for shared variables

  • Test fixtures belong in spec/fixtures/

  • Each class/module requires its own RSpec test file

  • Never use mocks or stubs — test against real objects

6. File Organization

Tests mirror the lib/ structure:

  • spec/uniword/ — Unit tests for core classes

  • spec/uniword/wordprocessingml/ — WordProcessingML element tests

  • spec/uniword/drawingml/ — DrawingML element tests

  • spec/uniword/smoke/ — Autoload and serializable model smoke tests

  • spec/integration/ — Integration tests

  • spec/performance/ — Performance benchmarks

  • spec/fixtures/ — Test fixture files (DOCX, XML, YAML)

7. Shared Test Support

spec/support/ provides reusable test infrastructure:

7.1. Shared Examples

Defined in spec/support/shared_examples.rb:

"a round-trippable serializable"

Verifies a lutaml-model class can serialize to XML and deserialize with attribute preservation.

"a round-trippable DOCX file"

Verifies a specific XML file within a DOCX preserves through round-trip using Canon XML comparison.

"a valid DOCX package"

Verifies a file is a valid ZIP with [Content_Types].xml, _rels/.rels, and word/document.xml.

"a serializable element"

Verifies a model responds to to_xml and produces parseable XML.

"a namespaced OOXML element"

Verifies root element name, parseable XML, and optional namespace URI.

7.2. Shared Helpers

Defined in spec/support/helpers.rb, included in all specs via RSpec.configure:

extract_text(document)

Extracts plain text from all paragraphs and table cells.

create_large_document(paragraphs:, runs_per_para:)

Creates a DocumentRoot with many paragraphs for performance testing.

create_document_with_tables(table_count:, rows:, cols:)

Creates a DocumentRoot with tables for performance testing.

normalize_xml(xml)

Parse and re-serialize XML for comparison.

temp_docx_path(prefix:)

Generates a unique temp file path for test output.

7.3. XML Normalization

spec/support/xml_normalizers.rb provides XmlNormalizers.normalize_for_roundtrip(xml) for handling acceptable XML differences (timestamps, statistics, unused namespaces).