rspec-xlsx_matchers 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 35beb1261a867c92fa8f9c4b27c260e70fb6c98491c5a1ec3944e4ac79baa090
+  data.tar.gz: 6c9abea563485512965144e52410175c2209a09551c60c5e896ea8110bc4d623
+SHA512:
+  metadata.gz: f5ab021b80d51fe3430f554ab04234074d4884bc9e0dd90e090e0d6718a9f5a432a771a520cba1b70a0375b099ba6d311fac9331e4d485da06d151691a877dd9
+  data.tar.gz: f08ca7a76cf5b4e781dfd6feda7054f7a63b7b7710611e5df8354f327da47de7f0c5dccdcfea5f91e8eb6e63209f30724117c5fe5c43c8266dd837679d8a2eda

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,31 @@
+require:
+  - rubocop-rspec
+  - rubocop-rake
+
+AllCops:
+  TargetRubyVersion: 3.0
+  NewCops: enable
+
+Style/StringLiterals:
+  Enabled: true
+  EnforcedStyle: double_quotes
+
+Style/StringLiteralsInInterpolation:
+  Enabled: true
+  EnforcedStyle: double_quotes
+
+Layout/LineLength:
+  Max: 120
+
+Naming/PredicateName:
+  NamePrefix: 
+    - is_
+
+RSpec/MultipleExpectations:
+  Enabled: false
+
+RSpec/ExampleLength:
+  Enabled: false
+
+RSpec/SubjectDeclaration:
+  Enabled: false

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [0.1.0] - 2024-05-29
+
+- Initial release

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 dreeven-oss
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,196 @@
+# RSpec::XlsxMatchers
+
+Provides rspec matchers for testing xlsx data with `roo` or `caxlsx` gems.
+
+## Optional dependencies
+
+ - [roo](https://github.com/roo-rb/roo)
+ - [caxlsx](https://github.com/caxlsx/caxlsx)
+
+## Configure
+  
+add `config.include RSpec::XlsxMatchers` to your RSpec.configure declaration
+
+```ruby
+# spec_helper.rb
+RSpec.configure do |config|
+  config.include RSpec::XlsxMatchers
+  # ...
+end
+```
+
+## Matchers
+
+### have_excel_sheets
+
+Tests that xlsx data contains specific sheets (by name or zero-based index)
+
+`subject` must be one of the following types:
+  - `String`: file path to an excel file (requires roo gem)
+  - `File`: file path to an excel file (requires roo gem)
+  - `Roo::Excelx`: excel file loaded with roo (requires roo gem)
+  - `Axlsx::Package`: (requires caxlsx gem)
+  - `Axlsx::Workbook`: (requires caxlsx gem)
+
+
+#### examples
+```ruby
+  it "has a sheet Sheet1" do
+    expect(subject).to have_excel_sheets("Sheet1")
+  end
+
+  it "has sheets Sheet1 and Sheet2" do
+    expect(subject).to have_excel_sheets(%w[Sheet1 Sheet2])
+  end
+
+  it "has at least 3 sheets" do
+    expect(subject).to have_excel_sheets(2)
+  end
+
+  it "has at least 3 sheets and a sheet named Sheet1" do
+    expect(subject).to have_excel_sheets([2, "Sheet1"])
+  end
+```
+
+### have_excel_columns
+
+Tests that a specific sheet contains some columns with specific value on the first row
+
+`subject` must be one of the following types:
+  - `String`: file path to an excel file (requires roo gem)
+  - `File`: file path to an excel file (requires roo gem)
+  - `Roo::Excelx`: excel file loaded with roo (requires roo gem)
+  - `Roo::Excelx::Sheet`: (requires roo gem)
+  - `Axlsx::Package`: (requires caxlsx gem)
+  - `Axlsx::Workbook`: (requires caxlsx gem)
+  - `Axlsx::Worksheet`: (requires caxlsx gem)
+
+#### chaining
+
+- `in_sheet(sheet_name)`: sheet where the data is expected. name (String) or index (Integer)
+  - **required** unless subject is a `Roo::Excelx::Sheet` or a `Axlsx::Worksheet`
+- `exactly`: Match columns in order and fail if extra columns are found
+
+#### examples
+```ruby
+  it "has a Gender and First Name columns in sheet Sheet 1" do
+    expect(subject).to have_excel_columns(["Gender", "First Name"]).in_sheet("Sheet1")
+  end
+
+  it "has column Last Name in first sheet" do
+    expect(subject).to have_excel_columns("Last Name").in_sheet(0)
+  end
+
+  it "has columns First Name and Last Name in first sheet, matching exactly" do
+    expect(subject).to have_excel_columns(["First Name", "Last Name"]).in_sheet(0).exactly
+  end
+```
+### have_excel_column
+
+Tests that a specific sheet contains columns with specific value on the first row
+
+`subject` must be one of the following types:
+  - `String`: file path to an excel file (requires roo gem)
+  - `File`: file path to an excel file (requires roo gem)
+  - `Roo::Excelx`: excel file loaded with roo (requires roo gem)
+  - `Roo::Excelx::Sheet`: (requires roo gem)
+  - `Axlsx::Package`: (requires caxlsx gem)
+  - `Axlsx::Workbook`: (requires caxlsx gem)
+  - `Axlsx::Worksheet`: (requires caxlsx gem)
+  
+
+#### chaining
+
+- `in_sheet(sheet_name)`: sheet where the data is expected. name (String) or index (Integer)
+  - **required** unless subject is a `Roo::Excelx::Sheet` or a `Axlsx::Worksheet`
+
+#### examples
+```ruby
+  it "has a Gender column in sheet Sheet 1" do
+    expect(subject).to have_excel_columns("Gender").in_sheet("Sheet1")
+  end
+
+  it "has a Last Name column in first sheet" do
+    expect(subject).to have_excel_columns("Last Name").in_sheet(0)
+  end
+```
+
+### have_excel_cells
+
+Tests that a specific row in a specific sheet contains the expected cell values
+
+`subject` must be one of the following types:
+  - `String`: file path to an excel file (requires roo gem)
+  - `File`: file path to an excel file (requires roo gem)
+  - `Roo::Excelx`: excel file loaded with roo (requires roo gem)
+  - `Roo::Excelx::Sheet`: (requires roo gem)
+  - `Axlsx::Package`: (requires caxlsx gem)
+  - `Axlsx::Workbook`: (requires caxlsx gem)
+  - `Axlsx::Worksheet`: (requires caxlsx gem)
+
+#### chaining
+
+- `in_sheet(sheet_name)`: sheet where the data is expected. name (String) or index (Integer, zero based)
+  - **required** unless subject is a `Roo::Excelx::Sheet` or a `Axlsx::Worksheet`
+- `in_row(row_index)`: row where the data is expected (row_index: Integer, zero-based)
+
+#### examples
+```ruby
+  it "has John Smith information on second row" do
+    expect(subject).to have_excel_cells(["John", "Smith", 24]).in_row(1).in_sheet("Sheet1")
+  end
+```
+
+### have_excel_empty_row
+
+Tests that a specific row in a specific sheet is empty
+
+`subject` must be one of the following types:
+  - `String`: file path to an excel file (requires roo gem)
+  - `File`: file path to an excel file (requires roo gem)
+  - `Roo::Excelx`: excel file loaded with roo (requires roo gem)
+  - `Roo::Excelx::Sheet`: (requires roo gem)
+  - `Axlsx::Package`: (requires caxlsx gem)
+  - `Axlsx::Workbook`: (requires caxlsx gem)
+  - `Axlsx::Worksheet`: (requires caxlsx gem)
+
+#### chaining
+
+- `in_sheet(sheet_name)`: sheet where the data is expected. name (String) or index (Integer)
+  - **required** unless subject is a `Roo::Excelx::Sheet` or a `Axlsx::Worksheet`
+
+
+#### examples
+```ruby
+  it "has no data on third row" do
+    expect(subject).to have_excel_empty_row(2)
+  end
+```
+
+### have_excel_cell_value
+
+Tests that a cell in a specific column of a specific row from a specific sheet has expected value
+
+`subject` must be one of the following types:
+  - `String`: file path to an excel file (requires roo gem)
+  - `File`: file path to an excel file (requires roo gem)
+  - `Roo::Excelx`: excel file loaded with roo (requires roo gem)
+  - `Roo::Excelx::Sheet`: (requires roo gem)
+  - `Axlsx::Package`: (requires caxlsx gem)
+  - `Axlsx::Workbook`: (requires caxlsx gem)
+  - `Axlsx::Worksheet`: (requires caxlsx gem)
+
+#### chaining
+
+- `in_sheet(sheet_name)`: sheet where the data is expected. name (String) or index (Integer, zero based)
+  - **required** unless subject is a `Roo::Excelx::Sheet` or a `Axlsx::Worksheet`
+- `in_row(row_index)`: row where the data is expected (row_index: Integer, zero-based)
+- `column(first_row_value)`: value of the column in the first row
+
+
+#### examples
+```ruby
+  it "has John in the First Name column of the third row of the first sheet" do
+    expect(subject).to have_excel_cell_value("John").in_sheet(0).in_row(2).in_column("First Name")
+  end
+```

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/lib/rspec/xlsx_matchers/base_sheet.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+module RSpec
+  module XlsxMatchers
+    # Base class for sheet based machers
+    class BaseSheet
+      include Utils
+      attr_reader :sheet_name, :sheet, :subject
+
+      def matches?(subject)
+        @subject = subject
+        @sheet = find_sheet
+        return false if sheet.nil?
+
+        process_sheet.tap do
+          finalize
+        end
+      end
+
+      def in_sheet(name)
+        @sheet_name = name
+        self
+      end
+
+      private
+
+      def find_sheet
+        find_axlsx_sheet || find_roo_sheet
+      rescue RangeError, ArgumentError
+        nil
+      end
+
+      def find_axlsx_sheet
+        return unless defined?(Axlsx)
+        return subject if subject.is_a?(Axlsx::Worksheet)
+
+        workbook = if subject.is_a?(Axlsx::Package)
+                     subject.workbook
+                   else
+                     subject
+                   end
+
+        return unless workbook.is_a?(Axlsx::Workbook)
+
+        axlsx_sheet_from_workbook(workbook)
+      end
+
+      def axlsx_sheet_from_workbook(workbook)
+        if sheet_name.is_a?(String)
+          workbook.sheet_by_name(sheet_name)
+        elsif sheet_name.is_a?(Integer)
+          workbook.worksheets[sheet_name]
+        else
+          raise ArgumentError, "Missing sheet name"
+        end
+      end
+
+      def find_roo_sheet
+        return unless defined?(Roo::Excelx)
+        return subject if subject.is_a?(Roo::Excelx::Sheet)
+
+        return unless roo_spreadsheet
+        return unless sheet_name
+
+        roo_spreadsheet.sheet_for(sheet_name)
+      end
+
+      def roo_spreadsheet
+        return @roo_spreadsheet unless @roo_spreadsheet.nil?
+
+        @roo_spreadsheet = if subject.is_a?(Roo::Excelx)
+                             subject
+                           elsif subject.is_a?(String) || subject.is_a?(File)
+                             Roo::Spreadsheet.open(subject)
+                           end
+      end
+
+      def process_sheet
+        if defined?(Axlsx) && sheet.is_a?(Axlsx::Worksheet)
+          process_axlsx_sheet
+        elsif defined?(Roo::Excelx) && sheet.is_a?(Roo::Excelx::Sheet)
+          process_roo_sheet
+        else
+          raise "Unsupported worksheet type: #{worksheet.class}"
+        end
+      end
+
+      def sheet_failure_message
+        if sheet_name
+          "Could not find sheet #{sheet_name}"
+        else
+          "Sheet not provided"
+        end
+      end
+
+      def failure_message_in_sheet(msg)
+        if sheet_name
+          "#{msg} in sheet #{sheet_name}"
+        else
+          msg
+        end
+      end
+
+      def finalize
+        roo_spreadsheet&.close
+      rescue StandardError => e
+        puts "Warning: error closing Roo Spreadsheet: #{e}"
+      end
+    end
+  end
+end

data/lib/rspec/xlsx_matchers/cell_value.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module RSpec
+  module XlsxMatchers
+    ## have_excel_cell_value
+    class CellValue < BaseSheet
+      include InRow
+      include InColumn
+      attr_reader :expected_value, :actual_value
+
+      def initialize(expected_value)
+        super()
+        @expected_value = expected_value
+      end
+
+      def failure_message
+        return sheet_failure_message if sheet.nil?
+        return header_column_not_found_message if header_column_not_found?
+        return row_not_found_message if row_not_found?
+        return column_not_found_message if column_not_found?
+
+        "Mismatch cell value in column '#{column_name}' of row '#{row_index}': " \
+          "expected: '#{expected_value}', received: '#{actual_value}'"
+      end
+
+      private
+
+      def process_axlsx_sheet
+        return false if header_column_not_found?
+        return false if row.nil?
+        return false if column_index.nil?
+
+        @actual_value = row[column_index]&.value
+        perform_match
+      end
+
+      def process_roo_sheet
+        return false if header_column_not_found?
+        return false if row.nil?
+        return false if column_index.nil?
+
+        @actual_value = row[column_index]
+        perform_match
+      end
+
+      def perform_match
+        convert_to_excel_value(expected_value) == actual_value
+      end
+
+      def convert_to_excel_value(value)
+        case value
+        when TrueClass
+          "1"
+        when FalseClass
+          "0"
+        else
+          value
+        end
+      end
+    end
+  end
+end

data/lib/rspec/xlsx_matchers/cells.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module RSpec
+  module XlsxMatchers
+    # have_excel_cells
+    class Cells < BaseSheet
+      include InRow
+      attr_reader :expected_cells, :actual_cells, :mismatch_indexes
+
+      EXPECTED = "Expected"
+      RECEIVED = "Received"
+
+      def initialize(expected_cells)
+        super()
+        @expected_cells = force_array(expected_cells)
+        @actual_cells = []
+        @mismatch_indexes = []
+      end
+
+      def failure_message # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
+        return sheet_failure_message if sheet.nil?
+        return row_not_found_message if row.nil?
+
+        message = failure_message_header(String.new("Rows did not match : \n"))
+        # Cells content
+        expected_cells.each_with_index do |expected_cell, idx|
+          sizeof_actual_cell = actual_cells[idx].to_s.size
+          sizeof_expected_cell = expected_cell.to_s.size
+          message << " #{idx}"
+          message << (" " * (4 - idx.to_s.size))
+          message << "| #{actual_cells[idx]}"
+          message << (" " * (biggest_actual_cell_size - sizeof_actual_cell))
+          message << " | #{expected_cell}"
+          message << (" " * (biggest_expected_cell_size - sizeof_expected_cell))
+          message << " | #{mismatch_indexes.include?(idx) ? "<----- Mismatch" : ""}"
+          message << "\n"
+        end
+        message
+      end
+
+      private
+
+      def process_axlsx_sheet
+        return false if row.nil?
+
+        @actual_cells = row.cells.map(&:value)
+        perform_match
+      end
+
+      def process_roo_sheet
+        return false if row.nil?
+
+        @actual_cells = row
+        perform_match
+      end
+
+      def perform_match
+        expected_cells.each_with_index do |expected_cell, idx|
+          actual_cell = actual_cells[idx]
+          mismatch_indexes << idx if actual_cell.to_s != expected_cell.to_s
+        end
+        mismatch_indexes.empty?
+      end
+
+      def biggest_actual_cell_size
+        @biggest_actual_cell_size ||= (actual_cells.map { |c| c.to_s.size } + [RECEIVED.size]).max
+      end
+
+      def biggest_expected_cell_size
+        @biggest_expected_cell_size ||= (expected_cells.map { |c| c.to_s.size } + [EXPECTED.size]).max
+      end
+
+      def failure_message_header(message) # rubocop:disable Metrics/AbcSize
+        # Table Header
+        message << "     | #{RECEIVED}"
+        message << (" " * (biggest_actual_cell_size - RECEIVED.size))
+        message << " | #{EXPECTED}"
+        message << (" " * (biggest_expected_cell_size - EXPECTED.size))
+        message << " |\n"
+        # Header / Content separator
+        message << ("#{"-" * 5}|#{"-" * (2 + biggest_actual_cell_size)}|#{"-" * (2 + @biggest_expected_cell_size)}|\n")
+        message
+      end
+    end
+  end
+end

data/lib/rspec/xlsx_matchers/columns.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+module RSpec
+  module XlsxMatchers
+    # have_excel_columns / have_excel_column
+    class Columns < BaseSheet
+      include ExactMatch
+      attr_reader :extra_columns, :missing_columns, :expected_columns, :actual_columns
+
+      def initialize(expected_columns)
+        super()
+        @expected_columns = force_array(expected_columns)
+        @missing_columns = []
+        @extra_columns = []
+        @actual_columns = []
+      end
+
+      def failure_message
+        return sheet_failure_message if sheet.nil?
+
+        msg = failure_message_in_sheet("Columns mismatch")
+
+        "#{msg}:\n\t#{column_failure_message}"
+      end
+
+      private
+
+      def process_axlsx_sheet
+        @actual_columns = sheet.rows[0]&.map(&:value)
+        if exact_match
+          perform_exact_match
+        else
+          perform_loose_match
+        end
+      end
+
+      def process_roo_sheet
+        @actual_columns = sheet.row(1)
+        if exact_match
+          perform_exact_match
+        else
+          perform_loose_match
+        end
+      end
+
+      def perform_exact_match
+        return true if expected_columns == actual_columns
+
+        (expected_columns - actual_columns).each do |column|
+          extra_columns << column
+        end
+
+        (actual_columns - expected_columns).each do |column|
+          missing_columns << column
+        end
+        false
+      end
+
+      def perform_loose_match
+        expected_columns.each do |column|
+          missing_columns << column unless actual_columns.include?(column)
+        end
+        missing_columns.empty?
+      end
+
+      def column_failure_message
+        column_mismatch_failure_message || column_order_failure_message
+      end
+
+      def column_order_failure_message
+        return unless exact_match
+
+        "Expected: #{map_output(expected_columns)}\n\t" \
+          "Received: #{map_output(actual_columns)}"
+      end
+
+      def column_mismatch_failure_message
+        msg = [missing_column_failure_message, extra_columns_failure_message].compact.join("\n\t")
+        if msg.empty?
+          nil
+        else
+          msg
+        end
+      end
+
+      def missing_column_failure_message
+        return if missing_columns.empty?
+
+        "Missing columns: #{map_output(missing_columns)}"
+      end
+
+      def extra_columns_failure_message
+        return if extra_columns.empty?
+
+        "Extra columns: #{map_output(extra_columns)}"
+      end
+    end
+  end
+end

data/lib/rspec/xlsx_matchers/empty_row.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module RSpec
+  module XlsxMatchers
+    # have_excel_empty_row
+    class EmptyRow < BaseSheet
+      attr_reader :row_index
+
+      def initialize(row_index)
+        super()
+        @row_index = row_index
+      end
+
+      def failure_message_when_negated
+        return sheet_failure_message if sheet.nil?
+
+        "Row at index '#{row_index}' was expected to NOT be empty, but was empty."
+      end
+
+      def failure_message
+        return sheet_failure_message if sheet.nil?
+
+        "Row at index '#{row_index}' was expected to be empty, but was not empty."
+      end
+
+      private
+
+      def process_axlsx_sheet
+        row = sheet.rows[row_index]
+        true if row.nil?
+      end
+
+      def process_roo_sheet
+        row = sheet.row(row_index).compact
+        true if row.empty?
+      end
+    end
+  end
+end

data/lib/rspec/xlsx_matchers/exact_match.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module RSpec
+  module XlsxMatchers
+    # common base for matchers with exact match option
+    module ExactMatch
+      attr_reader :exact_match
+
+      def exactly
+        @exact_match = true
+        self
+      end
+    end
+  end
+end

data/lib/rspec/xlsx_matchers/in_column.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module RSpec
+  module XlsxMatchers
+    # common base for columns matchers
+    module InColumn
+      attr_reader :column_name
+
+      def in_column(column_name)
+        @column_name = column_name
+        self
+      end
+
+      private
+
+      def column_index
+        return @column_index unless @column_index.nil?
+
+        return if sheet.nil? || column_row.nil?
+
+        find_column
+        @column_index
+      end
+
+      def column_row
+        return @column_row unless @column_row.nil?
+
+        @column_row = axlsx_column_row
+        @column_row = roo_column_row if @column_row.nil?
+        @column_row
+      end
+
+      def axlsx_column_row
+        sheet.rows[0]&.map(&:value) if defined?(Axlsx::Worksheet) && sheet.is_a?(Axlsx::Worksheet)
+      end
+
+      def roo_column_row
+        sheet.row(1) if defined?(Roo::Excelx) && sheet.is_a?(Roo::Excelx::Sheet)
+      rescue StandardError
+        # do nothing
+      end
+
+      def find_column
+        column_row.each_with_index do |c, i|
+          break unless @column_index.nil?
+
+          @column_index = i if c.to_s == column_name
+        end
+      end
+
+      def header_column_not_found?
+        column_row.nil? || column_row.compact.empty?
+      end
+
+      def header_column_not_found_message
+        "First row not found" if header_column_not_found?
+      end
+
+      def column_not_found?
+        column_index.nil?
+      end
+
+      def column_not_found_message
+        "Column #{column_name} not found"
+      end
+    end
+  end
+end

data/lib/rspec/xlsx_matchers/in_row.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module RSpec
+  module XlsxMatchers
+    # common base row based matchers
+    module InRow
+      attr_reader :row_index
+
+      def in_row(row_index)
+        @row_index = row_index
+        self
+      end
+
+      private
+
+      def row
+        return if sheet.nil?
+        return if row_index.nil?
+
+        @row ||= find_row
+      end
+
+      def find_row
+        if defined?(Axlsx::Worksheet) && sheet.is_a?(Axlsx::Worksheet)
+          sheet.rows[row_index]
+        elsif defined?(Roo::Excelx) && sheet.is_a?(Roo::Excelx::Sheet)
+          sheet.row(row_index + 1)
+        end
+      end
+
+      def row_not_found_message
+        "Row #{row_index} is empty" if row_not_found?
+      end
+
+      def row_not_found?
+        row.nil? || row.compact.empty?
+      end
+    end
+  end
+end

data/lib/rspec/xlsx_matchers/sheets.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module RSpec
+  module XlsxMatchers
+    # have_excel_sheets
+    class Sheets
+      include Utils
+      attr_reader :errors, :expected_sheet_names
+
+      def initialize(expected_sheet_names)
+        @expected_sheet_names = force_array expected_sheet_names
+        @errors = []
+      end
+
+      def matches?(subject)
+        if subject.is_a?(String) || subject.is_a?(File)
+          match_string(subject)
+        elsif defined?(Roo::Excelx) && subject.is_a?(Roo::Excelx)
+          match_roo_excelx(subject)
+        elsif defined?(Axlsx)
+          matches_axlsx?(subject)
+        else
+          invalid_file
+        end
+      end
+
+      def failure_message
+        "Xlsx file sheets not found: #{errors.map { |s| "'#{s}'" }.join(",")}"
+      end
+
+      private
+
+      def matches_axlsx?(subject)
+        if subject.is_a?(Axlsx::Package)
+          match_caxlsx(subject.workbook)
+        elsif defined?(Axlsx) && subject.is_a?(Axlsx::Workbook)
+          match_caxlsx(subject)
+        else
+          invalid_file
+        end
+      end
+
+      def invalid_file
+        raise ArgumentError, "Could not evaluate the sheets existance, " \
+                             "the matcher expected an instance of Roo::Excelx, " \
+                             "Axlsx::Package or Axlsx::Workbook, got #{excel_file.class}."
+      end
+
+      def match_caxlsx(excel_file)
+        return invalid_file unless defined?(Axlsx)
+
+        workbook = if excel_file.is_a?(Axlsx::Package)
+                     excel_file.workbook
+                   elsif excel_file.is_a?(Axlsx::Workbook)
+                     excel_file
+                   end
+
+        return invalid_file if workbook.nil?
+
+        match_caxlsx_workbook(workbook)
+      end
+
+      def match_caxlsx_workbook(workbook)
+        expected_sheet_names.each do |expected_sheet_name|
+          found = if expected_sheet_name.is_a?(String)
+                    workbook.sheet_by_name(expected_sheet_name)
+                  elsif expected_sheet_name.is_a?(Integer)
+                    workbook.worksheets[expected_sheet_name]
+                  end
+
+          errors << expected_sheet_name unless found.is_a?(Axlsx::Worksheet)
+        end
+        errors.empty?
+      end
+
+      def match_string(excel_file)
+        if defined?(Roo::Spreadsheet)
+          roo_file = Roo::Spreadsheet.open(excel_file)
+          match_roo_excelx(roo_file)
+        else
+          raise ArgumentError, "Could not evaluate the sheets existance, " \
+                               "the matcher received a string, but Roo::Spreadsheet is not defined"
+        end
+      end
+
+      def match_roo_excelx(excel_file)
+        expected_sheet_names.each do |expected_sheet_name|
+          excel_file.sheet(expected_sheet_name)
+        rescue ArgumentError, RangeError
+          errors << expected_sheet_name
+        rescue TypeError => e
+          errors << "#{expected_sheet_name} : #{e.message}"
+        end
+        errors.empty?
+      end
+    end
+  end
+end

data/lib/rspec/xlsx_matchers/utils.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module RSpec
+  module XlsxMatchers
+    # internal utilities
+    module Utils
+      def force_array(value)
+        if value.is_a?(Array)
+          value
+        else
+          [value]
+        end
+      end
+
+      def map_output(array)
+        array.map do |v|
+          if v.is_a?(String)
+            "'#{v}'"
+          else
+            v
+          end
+        end.join(", ")
+      end
+    end
+  end
+end

data/lib/rspec/xlsx_matchers/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module RSpec
+  module XlsxMatchers
+    VERSION = "0.1.0"
+  end
+end

data/lib/rspec/xlsx_matchers.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require_relative "xlsx_matchers/version"
+require_relative "xlsx_matchers/exact_match"
+require_relative "xlsx_matchers/in_row"
+require_relative "xlsx_matchers/in_column"
+require_relative "xlsx_matchers/utils"
+require_relative "xlsx_matchers/base_sheet"
+
+require_relative "xlsx_matchers/sheets"
+require_relative "xlsx_matchers/columns"
+require_relative "xlsx_matchers/empty_row"
+require_relative "xlsx_matchers/cells"
+require_relative "xlsx_matchers/cell_value"
+
+begin
+  require "roo"
+rescue LoadError
+  # optional dependency
+end
+
+begin
+  require "caxlsx"
+rescue LoadError
+  # optional dependency
+end
+module RSpec
+  # # RSpec::XlsxMatchers adds the following matchers to rspec
+  #  - have_excel_sheets
+  #  - have_excel_columns
+  #  - have_excel_column
+  #  - have_excel_empty_row
+  #  - have_excel_cells
+  #  - have_excel_cell_value
+  module XlsxMatchers
+    # class Error < StandardError; end
+
+    def have_excel_sheets(sheet_names)
+      Sheets.new(sheet_names)
+    end
+
+    def have_excel_columns(column_names)
+      Columns.new(column_names)
+    end
+
+    def have_excel_column(column_name)
+      raise ArgumentError, "Column name should not be an Array" if column_name.is_a?(Array)
+
+      Columns.new([column_name])
+    end
+
+    def have_excel_empty_row(index)
+      EmptyRow.new(index)
+    end
+
+    def have_excel_cells(cells)
+      Cells.new(cells)
+    end
+
+    def have_excel_cell_value(value)
+      CellValue.new(value)
+    end
+  end
+end

data/sig/rspec/xlsx_matchers.rbs

@@ -0,0 +1,6 @@
+module RSpec
+  module XlsxMatchers
+    VERSION: String
+    # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+  end
+end

metadata

@@ -0,0 +1,78 @@
+--- !ruby/object:Gem::Specification
+name: rspec-xlsx_matchers
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- drvn-eb
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2024-06-04 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+description: RSpec Xlsx matchers
+email:
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rspec"
+- ".rubocop.yml"
+- CHANGELOG.md
+- LICENSE
+- README.md
+- Rakefile
+- lib/rspec/xlsx_matchers.rb
+- lib/rspec/xlsx_matchers/base_sheet.rb
+- lib/rspec/xlsx_matchers/cell_value.rb
+- lib/rspec/xlsx_matchers/cells.rb
+- lib/rspec/xlsx_matchers/columns.rb
+- lib/rspec/xlsx_matchers/empty_row.rb
+- lib/rspec/xlsx_matchers/exact_match.rb
+- lib/rspec/xlsx_matchers/in_column.rb
+- lib/rspec/xlsx_matchers/in_row.rb
+- lib/rspec/xlsx_matchers/sheets.rb
+- lib/rspec/xlsx_matchers/utils.rb
+- lib/rspec/xlsx_matchers/version.rb
+- sig/rspec/xlsx_matchers.rbs
+homepage: https://github.com/dreeven-oss/rspec-xlsx_matchers
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/dreeven-oss/rspec-xlsx_matchers
+  source_code_uri: https://github.com/dreeven-oss/rspec-xlsx_matchers
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.19
+signing_key:
+specification_version: 4
+summary: RSpec Xlsx matchers
+test_files: []