Step Definitions that match a plain text Step with a multiline argument table will receive it as an instance of Table. A Table object holds the data of a table parsed from a feature file and lets you access and manipulate the data in different ways.
For example:
Given I have: | a | b | | c | d |
And a matching StepDefinition:
Given %rI have:/ do |table| data = table.raw end
This will store [['a', 'b'], ['c', 'd']]
in the
data
variable.
Creates a new instance. raw
should be an Array of Array of
String or an Array of Hash (similar to what hashes returns). You don't typically
create your own Table objects - Cucumber will do it internally and pass them
to your Step Definitions.
# File lib/cucumber/ast/table.rb, line 74 def initialize(raw, conversion_procs = NULL_CONVERSIONS.dup, header_mappings = {}, header_conversion_proc = nil) @cells_class = Cells @cell_class = Cell raw = ensure_array_of_array(rubify(raw)) # Verify that it's square transposed = raw.transpose create_cell_matrix(raw) @conversion_procs = conversion_procs @header_mappings = header_mappings @header_conversion_proc = header_conversion_proc end
# File lib/cucumber/ast/table.rb, line 62 def self.parse(text, uri, offset) builder = Builder.new lexer = Gherkin::Lexer::I18nLexer.new(builder) lexer.scan(text) new(builder.rows) end
Compares other_table
to self. If other_table
contains columns and/or rows that are not in self, new columns/rows are
added at the relevant positions, marking the cells in those rows/columns as
surplus
. Likewise, if other_table
lacks columns
and/or rows that are present in self, these are marked as
missing
.
surplus
and missing
cells are recognised by
formatters and displayed so that it's easy to read the differences.
Cells that are different, but look identical (for example the boolean true and the string "true") are converted to their Object#inspect representation and preceded with (i) - to make it easier to identify where the difference actually is.
Since all tables that are passed to StepDefinitions always have String objects in their cells, you may want to use map_column! before calling diff!. You can use map_column! on either of the tables.
A Different error is raised if there are
missing rows or columns, or surplus rows. An error is not raised
for surplus columns. Whether to raise or not raise can be changed by
setting values in options
to true or false:
missing_row
: Raise on missing rows (defaults to true)
surplus_row
: Raise on surplus rows (defaults to true)
missing_col
: Raise on missing columns (defaults to true)
surplus_col
: Raise on surplus columns (defaults to false)
The other_table
argument can be another Table, an Array of Array or an Array of Hash (similar
to the structure returned by hashes).
Calling this method is particularly useful in Then
steps that
take a Table argument, if you want to compare that
table to some actual values.
# File lib/cucumber/ast/table.rb, line 303 def diff!(other_table, options={}) options = {:missing_row => true, :surplus_row => true, :missing_col => true, :surplus_col => false}.merge(options) other_table = ensure_table(other_table) other_table.convert_headers! other_table.convert_columns! ensure_green! convert_headers! convert_columns! original_width = cell_matrix[0].length other_table_cell_matrix = pad!(other_table.cell_matrix) padded_width = cell_matrix[0].length missing_col = cell_matrix[0].detect{|cell| cell.status == :undefined} surplus_col = padded_width > original_width require_diff_lcs cell_matrix.extend(Diff::LCS) changes = cell_matrix.diff(other_table_cell_matrix).flatten inserted = 0 missing = 0 row_indices = Array.new(other_table_cell_matrix.length) {|n| n} last_change = nil missing_row_pos = nil insert_row_pos = nil changes.each do |change| if(change.action == '-') missing_row_pos = change.position + inserted cell_matrix[missing_row_pos].each{|cell| cell.status = :undefined} row_indices.insert(missing_row_pos, nil) missing += 1 else # '+' insert_row_pos = change.position + missing inserted_row = change.element inserted_row.each{|cell| cell.status = :comment} cell_matrix.insert(insert_row_pos, inserted_row) row_indices[insert_row_pos] = nil inspect_rows(cell_matrix[missing_row_pos], inserted_row) if last_change && last_change.action == '-' inserted += 1 end last_change = change end other_table_cell_matrix.each_with_index do |other_row, i| row_index = row_indices.index(i) row = cell_matrix[row_index] if row_index if row (original_width..padded_width).each do |col_index| surplus_cell = other_row[col_index] row[col_index].value = surplus_cell.value if row[col_index] end end end clear_cache! should_raise = missing_row_pos && options[:missing_row] || insert_row_pos && options[:surplus_row] || missing_col && options[:missing_col] || surplus_col && options[:surplus_col] raise Different.new(self) if should_raise end
Creates a copy of this table, inheriting any column and header mappings registered with map_column! and map_headers!.
# File lib/cucumber/ast/table.rb, line 93 def dup self.class.new(raw.dup, @conversion_procs.dup, @header_mappings.dup, @header_conversion_proc) end
Converts this table into an Array of Hash where the keys of each Hash are the headers in the table. For example, a Table built from the following plain text:
| a | b | sum | | 2 | 3 | 5 | | 7 | 9 | 16 |
Gets converted into the following:
[{'a' => '2', 'b' => '3', 'sum' => '5'}, {'a' => '7', 'b' => '9', 'sum' => '16'}]
Use map_column! to specify how values in a column are converted.
# File lib/cucumber/ast/table.rb, line 126 def hashes @hashes ||= build_hashes end
Change how hashes converts column
values. The column_name
argument identifies the column and
conversion_proc
performs the conversion for each cell in that
column. If strict
is true, an error will be raised if the
column named column_name
is not found. If strict
is false, no error will be raised. Example:
Given %r^an expense report for (.*) with the following posts:$/ do |table| posts_table.map_column!('amount') { |a| a.to_i } posts_table.hashes.each do |post| # post['amount'] is a Fixnum, rather than a String end end
# File lib/cucumber/ast/table.rb, line 264 def map_column!(column_name, strict=true, &conversion_proc) @conversion_procs[column_name.to_s] = { :strict => strict, :proc => conversion_proc } self end
Returns a new Table where the headers are redefined. See map_headers!
# File lib/cucumber/ast/table.rb, line 246 def map_headers(mappings={}) table = self.dup table.map_headers!(mappings) table end
Redefines the table headers. This makes it possible to use prettier and
more flexible header names in the features. The keys of
mappings
are Strings or regular expressions (anything that
responds to #=== will work) that may match column headings in the table.
The values of mappings
are desired names for the columns.
Example:
| Phone Number | Address | | 123456 | xyz | | 345678 | abc |
A StepDefinition receiving this table can then map the columns with both Regexp and String:
table.map_headers!(%rphone( number)?/ => :phone, 'Address' => :address) table.hashes # => [{:phone => '123456', :address => 'xyz'}, {:phone => '345678', :address => 'abc'}]
You may also pass in a block if you wish to convert all of the headers:
table.map_headers! { |header| header.downcase } table.hashes.keys # => ['phone number', 'address']
When a block is passed in along with a hash then the mappings in the hash take precendence:
table.map_headers!('Address' => 'ADDRESS') { |header| header.downcase } table.hashes.keys # => ['phone number', 'ADDRESS']
# File lib/cucumber/ast/table.rb, line 240 def map_headers!(mappings={}, &block) @header_mappings = mappings @header_conversion_proc = block end
Matches pattern
against the header row of the table. This is
used especially for argument transforms.
Example:
| column_1_name | column_2_name | | x | y | table.match(%rtable:column_1_name,column_2_name/) #=> non-nil
Note: must use 'table:' prefix on match
# File lib/cucumber/ast/table.rb, line 198 def match(pattern) header_to_match = "table:#{headers.join(',')}" pattern.match(header_to_match) end
Gets the raw data of this table. For example, a Table built from the following plain text:
| a | b | | c | d |
gets converted into the following:
[['a', 'b'], ['c', 'd']]
# File lib/cucumber/ast/table.rb, line 158 def raw cell_matrix.map do |row| row.map do |cell| cell.value end end end
# File lib/cucumber/ast/table.rb, line 170 def rows hashes.map do |hash| hash.values_at *headers end end
Converts this table into a Hash where the first column is used as keys and the second column is used as values
| a | 2 | | b | 3 |
Gets converted into the following:
{'a' => '2', 'b' => '3'}
The table must be exactly two columns wide
# File lib/cucumber/ast/table.rb, line 142 def rows_hash return @rows_hash if @rows_hash verify_table_width(2) @rows_hash = self.transpose.hashes[0] end
# File lib/cucumber/ast/table.rb, line 86 def to_step_definition_arg dup end
Returns a new, transposed table. Example:
| a | 7 | 4 | | b | 9 | 2 |
Gets converted into the following:
| a | b | | 7 | 9 | | 4 | 2 |
# File lib/cucumber/ast/table.rb, line 108 def transpose self.class.new(raw.transpose, @conversion_procs.dup, @header_mappings.dup, @header_conversion_proc) end
# File lib/cucumber/ast/table.rb, line 460 def build_hashes convert_headers! convert_columns! cells_rows[1..-1].map do |row| row.to_hash end end
# File lib/cucumber/ast/table.rb, line 588 def ensure_array_of_array(array) Hash === array[0] ? hashes_to_array(array) : array end