canon 0.1.3 → 0.1.5

data/docs/RSPEC.adoc

@@ -0,0 +1,605 @@
+---
+layout: default
+title: RSpec Matchers
+nav_order: 12
+parent: Basic Usage
+---
+= Canon RSpec matchers
+:toc:
+:toclevels: 3
+
+== Scope
+
+This document describes how to use Canon's RSpec matchers for testing. Canon
+provides semantic comparison matchers that focus on content rather than
+formatting.
+
+For Ruby API usage, see link:RUBY_API[Ruby API documentation].
+
+For command-line usage, see link:CLI[CLI documentation].
+
+== General
+
+Canon's RSpec matchers use canonical (c14n) mode for comparison, ensuring that
+formatting differences don't affect test results. Tests focus on semantic
+equivalence rather than exact string matching.
+
+== Installation
+
+Add to your `spec_helper.rb` or `spec/support/canon.rb`:
+
+[source,ruby]
+----
+require 'canon/rspec_matchers'
+----
+
+== Basic usage
+
+=== Unified matcher
+
+The `be_serialization_equivalent_to` matcher works with all formats:
+
+.Unified matcher syntax
+[example]
+====
+[source,ruby]
+----
+require 'canon/rspec_matchers'
+
+RSpec.describe 'Serialization' do
+  it 'compares XML' do
+    xml1 = '<root><a>1</a><b>2</b></root>'
+    xml2 = '<root>  <b>2</b>  <a>1</a>  </root>'
+    expect(xml1).to be_serialization_equivalent_to(xml2, format: :xml)
+  end
+
+  it 'compares HTML' do
+    html1 = '<div><p>Hello</p></div>'
+    html2 = '<div> <p> Hello </p> </div>'
+    expect(html1).to be_serialization_equivalent_to(html2, format: :html)
+  end
+
+  it 'compares JSON' do
+    json1 = '{"a":1,"b":2}'
+    json2 = '{"b":2,"a":1}'
+    expect(json1).to be_serialization_equivalent_to(json2, format: :json)
+  end
+
+  it 'compares YAML' do
+    yaml1 = "a: 1\nb: 2"
+    yaml2 = "b: 2\na: 1"
+    expect(yaml1).to be_serialization_equivalent_to(yaml2, format: :yaml)
+  end
+end
+----
+====
+
+=== Format-specific matchers
+
+Canon provides dedicated matchers for each format:
+
+.Format-specific matchers
+[example]
+====
+[source,ruby]
+----
+RSpec.describe 'Format-specific matchers' do
+  it 'uses XML matcher' do
+    expect(actual_xml).to be_xml_equivalent_to(expected_xml)
+    # or legacy alias
+    expect(actual_xml).to be_analogous_with(expected_xml)
+  end
+
+  it 'uses HTML matcher' do
+    expect(actual_html).to be_html_equivalent_to(expected_html)
+  end
+
+  it 'uses JSON matcher' do
+    expect(actual_json).to be_json_equivalent_to(expected_json)
+  end
+
+  it 'uses YAML matcher' do
+    expect(actual_yaml).to be_yaml_equivalent_to(expected_yaml)
+  end
+end
+----
+====
+
+== Global configuration
+
+Configure matchers globally in your `spec_helper.rb`:
+
+=== Syntax
+
+[source,ruby]
+----
+Canon::RSpecMatchers.configure do |config|
+  config.<format>.match.profile = :profile_name
+  config.<format>.match.options = { ... }
+  config.<format>.diff.mode = :mode_name
+  config.<format>.diff.use_color = true/false
+  config.<format>.diff.context_lines = n
+  config.<format>.diff.grouping_lines = n
+end
+----
+
+Where `<format>` is one of: `xml`, `html`, `json`, `yaml`
+
+=== Match configuration
+
+.Match profiles
+[example]
+====
+[source,ruby]
+----
+# spec_helper.rb
+Canon::RSpecMatchers.configure do |config|
+  # Use spec_friendly profile for XML
+  config.xml.match.profile = :spec_friendly
+
+  # Use rendered profile for HTML
+  config.html.match.profile = :rendered
+
+  # Use strict profile for JSON
+  config.json.match.profile = :strict
+end
+----
+
+Available profiles: `:strict`, `:rendered`, `:spec_friendly`, `:content_only`
+
+See link:MATCH_OPTIONS[Match options] for profile details.
+====
+
+.Match dimension options
+[example]
+====
+[source,ruby]
+----
+# spec_helper.rb
+Canon::RSpecMatchers.configure do |config|
+  config.xml.match.options = {
+    text_content: :normalize,
+    structural_whitespace: :ignore,
+    attribute_order: :ignore,
+    comments: :ignore
+  }
+
+  config.html.match.options = {
+    text_content: :normalize,
+    structural_whitespace: :ignore
+  }
+
+  config.json.match.options = {
+    key_order: :ignore
+  }
+end
+----
+
+See link:MATCH_OPTIONS[Match options] for dimension reference.
+====
+
+=== Diff configuration
+
+.Diff mode and colors
+[example]
+====
+[source,ruby]
+----
+# spec_helper.rb
+Canon::RSpecMatchers.configure do |config|
+  # XML with by-line mode
+  config.xml.diff.mode = :by_line
+  config.xml.diff.use_color = true
+
+  # HTML with by-line mode
+  config.html.diff.mode = :by_line
+
+  # JSON with by-object mode (default)
+  config.json.diff.mode = :by_object
+  config.json.diff.use_color = true
+end
+----
+
+See link:MODES[Diff modes] for mode details.
+====
+
+.Diff formatting
+[example]
+====
+[source,ruby]
+----
+# spec_helper.rb
+Canon::RSpecMatchers.configure do |config|
+  # Show 5 lines of context
+  config.xml.diff.context_lines = 5
+
+  # Group changes within 10 lines
+  config.xml.diff.grouping_lines = 10
+
+  # Disable colors for CI environments
+  config.xml.diff.use_color = !ENV['CI']
+end
+----
+
+See link:DIFF_FORMATTING[Diff formatting] for options.
+====
+
+=== Complete configuration example
+
+.Full configuration
+[example]
+====
+[source,ruby]
+----
+# spec_helper.rb
+require 'canon/rspec_matchers'
+
+Canon::RSpecMatchers.configure do |config|
+  # XML configuration
+  config.xml.match.profile = :spec_friendly
+  config.xml.match.options = {
+    text_content: :normalize,
+    structural_whitespace: :ignore,
+    comments: :ignore
+  }
+  config.xml.diff.mode = :by_line
+  config.xml.diff.use_color = true
+  config.xml.diff.context_lines = 3
+
+  # HTML configuration
+  config.html.match.profile = :rendered
+  config.html.diff.mode = :by_line
+  config.html.diff.grouping_lines = 2
+
+  # JSON configuration
+  config.json.match.profile = :spec_friendly
+  config.json.match.options = {
+    key_order: :ignore
+  }
+  config.json.diff.mode = :by_object
+  config.json.diff.context_lines = 5
+
+  # YAML configuration
+  config.yaml.match.options = {
+    key_order: :ignore
+  }
+end
+----
+====
+
+== Per-test configuration
+
+Override global configuration on a per-test basis using matcher options.
+
+=== Using match profiles
+
+.Override with profile
+[example]
+====
+[source,ruby]
+----
+RSpec.describe 'Override global config' do
+  it 'uses strict matching for this test' do
+    expect(actual_xml).to be_xml_equivalent_to(expected_xml)
+      .with_profile(:strict)
+  end
+
+  it 'uses rendered profile for HTML' do
+    expect(actual_html).to be_html_equivalent_to(expected_html)
+      .with_profile(:rendered)
+  end
+end
+----
+====
+
+=== Using match options
+
+.Override with specific dimensions
+[example]
+====
+[source,ruby]
+----
+RSpec.describe 'Override specific dimensions' do
+  it 'requires strict whitespace for this test' do
+    expect(actual_xml).to be_xml_equivalent_to(expected_xml)
+      .with_options(
+        structural_whitespace: :strict,
+        text_content: :strict
+      )
+  end
+
+  it 'ignores attribute order' do
+    expect(actual_xml).to be_xml_equivalent_to(expected_xml)
+      .with_options(attribute_order: :ignore)
+  end
+end
+----
+====
+
+=== Combining profile and options
+
+.Profile with overrides
+[example]
+====
+[source,ruby]
+----
+RSpec.describe 'Combine profile and options' do
+  it 'uses spec_friendly but checks comments' do
+    expect(actual_xml).to be_xml_equivalent_to(expected_xml)
+      .with_profile(:spec_friendly)
+      .with_options(comments: :strict)
+  end
+
+  it 'uses rendered but requires strict text' do
+    expect(actual_html).to be_html_equivalent_to(expected_html)
+      .with_profile(:rendered)
+      .with_options(text_content: :strict)
+  end
+end
+----
+====
+
+== Verbose output
+
+Use `verbose: true` to show detailed diff output on test failures.
+
+.Verbose diff examples
+[example]
+====
+[source,ruby]
+----
+RSpec.describe 'Verbose diff output' do
+  it 'shows detailed XML diff on failure' do
+    expect(actual_xml).to be_xml_equivalent_to(expected_xml, verbose: true)
+  end
+
+  it 'shows detailed HTML diff on failure' do
+    expect(actual_html).to be_html_equivalent_to(expected_html, verbose: true)
+  end
+
+  it 'shows detailed JSON diff on failure' do
+    expect(actual_json).to be_json_equivalent_to(expected_json, verbose: true)
+  end
+
+  # Combine with profile and options
+  it 'shows verbose diff with custom options' do
+    expect(actual_xml).to be_xml_equivalent_to(expected_xml, verbose: true)
+      .with_profile(:spec_friendly)
+      .with_options(comments: :strict)
+  end
+end
+----
+====
+
+== Common patterns
+
+=== Testing XML generation
+
+.XML generation tests
+[example]
+====
+[source,ruby]
+----
+RSpec.describe 'XML generation' do
+  let(:expected_xml) do
+    <<~XML
+      <document>
+        <title>Test Document</title>
+        <content>
+          <p>Paragraph content</p>
+        </content>
+      </document>
+    XML
+  end
+
+  it 'generates correct XML structure' do
+    actual_xml = generate_xml(title: 'Test Document',
+                               content: '<p>Paragraph content</p>')
+
+    expect(actual_xml).to be_xml_equivalent_to(expected_xml)
+  end
+
+  it 'handles attributes correctly' do
+    actual = generate_element(id: '123', class: 'active')
+    expected = '<element class="active" id="123"/>'
+
+    # Attribute order doesn't matter with default config
+    expect(actual).to be_xml_equivalent_to(expected)
+  end
+end
+----
+====
+
+=== Testing HTML output
+
+.HTML output tests
+[example]
+====
+[source,ruby]
+----
+RSpec.describe 'HTML generation' do
+  let(:expected_html) do
+    <<~HTML
+      <!DOCTYPE html>
+      <html>
+        <head>
+          <title>Test Page</title>
+        </head>
+        <body>
+          <h1>Welcome</h1>
+          <p>Content here</p>
+        </body>
+      </html>
+    HTML
+  end
+
+  it 'generates correct HTML' do
+    actual_html = generate_page(
+      title: 'Test Page',
+      heading: 'Welcome',
+      content: 'Content here'
+    )
+
+    expect(actual_html).to be_html_equivalent_to(expected_html)
+  end
+
+  # Formatting differences are ignored
+  it 'ignores whitespace differences' do
+    compact = '<div><p>Text</p></div>'
+    pretty = <<~HTML
+      <div>
+        <p>Text</p>
+      </div>
+    HTML
+
+    expect(compact).to be_html_equivalent_to(pretty)
+  end
+end
+----
+====
+
+=== Testing JSON APIs
+
+.JSON API tests
+[example]
+====
+[source,ruby]
+----
+RSpec.describe 'API responses' do
+  let(:expected_response) do
+    {
+      "user" => {
+        "id" => 123,
+        "name" => "John Doe",
+        "email" => "john@example.com"
+      },
+      "status" => "success"
+    }.to_json
+  end
+
+  it 'returns correct user data' do
+    response = api_client.get_user(123)
+
+    expect(response).to be_json_equivalent_to(expected_response)
+  end
+
+  # Key order doesn't matter with default config
+  it 'ignores key ordering' do
+    actual = '{"b":2,"a":1}'
+    expected = '{"a":1,"b":2}'
+
+    expect(actual).to be_json_equivalent_to(expected)
+  end
+end
+----
+====
+
+=== Testing configuration files
+
+.Configuration file tests
+[example]
+====
+[source,ruby]
+----
+RSpec.describe 'Configuration files' do
+  it 'generates correct YAML config' do
+    config = generate_config(
+      database: { host: 'localhost', port: 5432 },
+      logging: { level: 'info' }
+    )
+
+    expected = <<~YAML
+      database:
+        host: localhost
+        port: 5432
+      logging:
+        level: info
+    YAML
+
+    expect(config).to be_yaml_equivalent_to(expected)
+  end
+
+  it 'handles nested structures' do
+    actual_yaml = to_yaml(deeply: { nested: { structure: 'value' } })
+    expected_yaml = "deeply:\n  nested:\n    structure: value"
+
+    expect(actual_yaml).to be_yaml_equivalent_to(expected_yaml)
+  end
+end
+----
+====
+
+== Troubleshooting
+
+=== Debugging test failures
+
+When a test fails, Canon shows a detailed diff. Use verbose mode for maximum
+detail:
+
+.Debugging example
+[example]
+====
+[source,ruby]
+----
+it 'shows exactly what differs' do
+  expect(actual).to be_xml_equivalent_to(expected, verbose: true)
+    .with_profile(:strict)  # Use strict to see all differences
+end
+----
+
+The diff output will show:
+
+* Line numbers
+* Color-coded changes (red/green)
+* Whitespace visualization
+* Non-ASCII character warnings
+====
+
+=== Temporarily disabling global config
+
+.Override global config
+[example]
+====
+[source,ruby]
+----
+it 'uses different config for this test' do
+  # Global config uses spec_friendly, but we want strict here
+  expect(actual).to be_xml_equivalent_to(expected)
+    .with_profile(:strict)
+    .with_options(
+      text_content: :strict,
+      structural_whitespace: :strict
+    )
+end
+----
+====
+
+=== Checking what's being compared
+
+.Debug preprocessed content
+[example]
+====
+[source,ruby]
+----
+# In your test, temporarily add:
+result = Canon::Comparison.equivalent?(actual, expected, verbose: true)
+
+# Inspect preprocessed content
+puts "Preprocessed actual:"
+puts result[:preprocessed][0]
+
+puts "Preprocessed expected:"
+puts result[:preprocessed][1]
+
+puts "Differences:"
+pp result[:differences]
+----
+====
+
+== See also
+
+* link:RUBY_API[Ruby API documentation]
+* link:CLI[Command-line interface]
+* link:MATCH_OPTIONS[Match options reference]
+* link:MODES[Diff modes]
+* link:DIFF_FORMATTING[Diff formatting options]