Task-oriented tutorials for common Canon use cases.

1. Overview

This section provides step-by-step guides for accomplishing specific tasks with Canon. Each guide walks you through a complete workflow from start to finish.

Unlike reference documentation that explains individual features, these guides show you how to combine features to solve real problems.

2. Available Guides

Testing XML Generation

How to use Canon in RSpec tests to validate generated XML output.

Covers: RSpec matchers, match profiles, handling whitespace, debugging failures.

Debugging Test Failures

Strategies for diagnosing and fixing test failures when comparing documents.

Covers: Verbose mode, character visualization, match dimension tuning, common pitfalls.

Migrating from XMLDiff

Guide for users switching from other XML comparison tools.

Covers: Feature mapping, option translation, behavior differences, migration checklist.

Performance Optimization

Techniques for improving comparison performance on large documents.

Covers: Algorithm selection, size limits, preprocessing strategies, batch processing.

Building Custom Comparators

How to extend Canon with custom comparison logic for specialized formats.

Covers: Comparator interface, adapter pattern, integration, testing.

3. By Use Case

3.1. Testing and QA

Writing reliable XML tests

Testing XML Generation shows how to use Canon’s RSpec matchers for robust testing.

Debugging test failures

Debugging Test Failures provides systematic troubleshooting strategies.

Comparing configuration files

Use Match Profiles with the spec_friendly profile.

3.2. Migration and Integration

Switching from another tool

Migrating from XMLDiff helps you transition smoothly.

Integrating into CI/CD

See CLI Reference for command-line usage in pipelines.

Adding to existing test suite

Testing XML Generation covers integration patterns.

3.3. Performance and Scale

Handling large files

Performance Optimization shows strategies for large documents.

Batch processing

See Batch Processing section.

Optimizing comparison speed

Algorithm Selection explains trade-offs.

3.4. Customization and Extension

Custom comparison logic

Building Custom Comparators walks through the process.

Format-specific handling

See Extending Canon for adapter development.

4. Guide Structure

Each guide follows this structure:

Overview

What you’ll learn and prerequisites.

Problem

The real-world problem this guide solves.

Solution

Step-by-step walkthrough with code examples.

Explanation

Why the solution works and alternatives to consider.

Summary

Key takeaways and next steps.

5. Prerequisites

Most guides assume:

  • Ruby 2.7 or higher installed

  • Basic familiarity with Canon concepts

  • Understanding of the format you’re working with

If you’re new to Canon, start with Getting Started first.

6. Common Patterns

6.1. Test-Friendly Comparison 

# Ignore formatting differences in tests
expect(actual_xml).to be_xml_equivalent_to(expected_xml,
  match_profile: :spec_friendly
)

See Test-Friendly Matching.

6.2. Detailed Debugging 

# Get detailed diff output
result = Canon::Comparison.compare(expected, actual,
  verbose: true,
  visualize_whitespace: true,
  context_lines: 10
)
puts result.diff

See Verbose Output.

6.3. Performance Tuning 

# Optimize for large files
Canon::Comparison.equivalent?(doc1, doc2,
  preprocessing: :none,  # Skip preprocessing
  diff_algorithm: :dom,  # Use faster algorithm
  max_nodes: 50000       # Increase limit if needed
)

See Tuning Options.

7. Getting Help

Can’t find what you need?

Check Reference for complete option listings.

Need conceptual understanding?

See Understanding Canon for architectural details.

Want to contribute a guide?

See Contributing Guidelines.

8. Next Steps

  • Choose a guide that matches your current task

  • Follow along with the code examples

  • Experiment with variations

  • Share your learnings with the community

9. See Also

Table of contents