Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

Improve documentation

  • Loading branch information...
commit 8146e5d5b5e8cfd9cc6ae860bf60944fdf27beb4 1 parent b934a30
Aslak Hellesøy aslakhellesoy authored
Showing with 230 additions and 196 deletions.
  1. +1 −0  History.txt
  2. +2 −2 Manifest.txt
  3. +1 −0  gem_tasks/features.rake
  4. +7 −0 gem_tasks/sdoc.rake
  5. +0 −8 gem_tasks/yard.rake
  6. +12 −0 lib/README.rdoc
  7. +1 −1  lib/cucumber/ast/background.rb
  8. +1 −1  lib/cucumber/ast/comment.rb
  9. +1 −1  lib/cucumber/ast/examples.rb
  10. +1 −1  lib/cucumber/ast/feature.rb
  11. +1 −1  lib/cucumber/ast/feature_element.rb
  12. +1 −1  lib/cucumber/ast/features.rb
  13. +2 −2 lib/cucumber/ast/outline_table.rb
  14. +1 −1  lib/cucumber/ast/py_string.rb
  15. +1 −1  lib/cucumber/ast/scenario.rb
  16. +2 −2 lib/cucumber/ast/scenario_outline.rb
  17. +1 −1  lib/cucumber/ast/step.rb
  18. +1 −1  lib/cucumber/ast/step_collection.rb
  19. +1 −1  lib/cucumber/ast/step_invocation.rb
  20. +61 −43 lib/cucumber/ast/table.rb
  21. +1 −1  lib/cucumber/ast/tags.rb
  22. +6 −8 lib/cucumber/ast/visitor.rb
  23. +1 −1  lib/cucumber/broadcaster.rb
  24. +1 −1  lib/cucumber/constantize.rb
  25. +1 −1  lib/cucumber/core_ext/exception.rb
  26. +8 −3 lib/cucumber/core_ext/instance_exec.rb
  27. +1 −1  lib/cucumber/core_ext/proc.rb
  28. +1 −1  lib/cucumber/core_ext/string.rb
  29. +4 −3 lib/cucumber/feature_file.rb
  30. +2 −1  lib/cucumber/filter.rb
  31. +6 −5 lib/cucumber/formatter/ansicolor.rb
  32. +1 −1  lib/cucumber/formatter/color_io.rb
  33. +2 −0  lib/cucumber/formatter/console.rb
  34. +3 −0  lib/cucumber/formatter/duration.rb
  35. +1 −0  lib/cucumber/formatter/html.rb
  36. +1 −0  lib/cucumber/formatter/junit.rb
  37. +1 −1  lib/cucumber/formatter/ordered_xml_markup.rb
  38. +2 −0  lib/cucumber/formatter/pretty.rb
  39. +1 −0  lib/cucumber/formatter/profile.rb
  40. +1 −0  lib/cucumber/formatter/progress.rb
  41. +2 −0  lib/cucumber/formatter/rerun.rb
  42. +1 −0  lib/cucumber/formatter/steps.rb
  43. +2 −1  lib/cucumber/formatter/tag_cloud.rb
  44. +1 −1  lib/cucumber/formatter/unicode.rb
  45. +1 −0  lib/cucumber/formatter/usage.rb
  46. +6 −5 lib/cucumber/parser/treetop_ext.rb
  47. +1 −2  lib/cucumber/platform.rb
  48. +2 −1  lib/cucumber/rails/world.rb
  49. +13 −11 lib/cucumber/rake/task.rb
  50. +9 −9 lib/cucumber/rb_support/rb_dsl.rb
  51. +1 −0  lib/cucumber/rb_support/rb_hook.rb
  52. +3 −0  lib/cucumber/rb_support/rb_language.rb
  53. +4 −2 lib/cucumber/rb_support/rb_step_definition.rb
  54. +3 −3 lib/cucumber/rspec_neuter.rb
  55. +2 −2 lib/cucumber/step_match.rb
  56. +26 −29 lib/cucumber/step_mother.rb
  57. +1 −1  lib/cucumber/version.rb
  58. +3 −3 lib/cucumber/webrat/element_locator.rb
  59. +5 −3 lib/cucumber/world.rb
  60. +0 −27 spec/cucumber/ast/visitor_spec.rb
1  History.txt
View
@@ -4,6 +4,7 @@
* Table.map_headers! will fail with a decent error message when 0 or 2+ headers are matched. (Aslak Hellesøy)
=== New Features
+* The public API is documented and there is a new :sdoc task to generate nice searchable API docs.
* Add :default => :cucumber when setting up Rake tasks for Cucumber in Rails (Aslak Hellesøy)
* New When /^I fill in "([^\"]*)" for "([^\"]*)"$/ Webrat step for Rails (Aslak Hellesøy)
4 Manifest.txt
View
@@ -289,7 +289,8 @@ gem_tasks/flog.rake
gem_tasks/gemspec.rake
gem_tasks/rspec.rake
gem_tasks/sass.rake
-gem_tasks/yard.rake
+gem_tasks/sdoc.rake
+lib/README.rdoc
lib/autotest/cucumber.rb
lib/autotest/cucumber_mixin.rb
lib/autotest/cucumber_rails.rb
@@ -396,7 +397,6 @@ spec/cucumber/ast/scenario_spec.rb
spec/cucumber/ast/step_collection_spec.rb
spec/cucumber/ast/step_spec.rb
spec/cucumber/ast/table_spec.rb
-spec/cucumber/ast/visitor_spec.rb
spec/cucumber/broadcaster_spec.rb
spec/cucumber/cli/configuration_spec.rb
spec/cucumber/cli/drb_client_spec.rb
1  gem_tasks/features.rake
View
@@ -3,6 +3,7 @@ require 'cucumber/rake/task'
Cucumber::Rake::Task.new do |t|
t.cucumber_opts = %w{--format progress}
+ t.rcov = ENV['RCOV']
end
Cucumber::Rake::Task.new('pretty') do |t|
7 gem_tasks/sdoc.rake
View
@@ -0,0 +1,7 @@
+require 'sdoc' # and use your RDoc task the same way you used it before
+
+Rake::RDocTask.new(:sdoc) do |rdoc|
+ rdoc.rdoc_dir = 'doc/sdoc'
+ rdoc.options += %w{--fmt shtml -N --webcvs=http://github.com/aslakhellesoy/cucumber/blob/v0.3.96/%s --title "Cucumber API" --threads 4 --main README --exclude cucumber/parser lib}
+ rdoc.template = 'direct' # lighter template used on railsapi.com
+end
8 gem_tasks/yard.rake
View
@@ -1,8 +0,0 @@
-begin
- require 'yard'
-
- YARD::Rake::YardocTask.new do |t|
- t.files = ['lib/**/*.rb']
- end
-rescue LoadError => ignore
-end
12 lib/README.rdoc
View
@@ -0,0 +1,12 @@
+= Cucumber API
+
+This is the public API of Cucumber. The public API includes the classes, modules
+and methods you can use if you are a user of Cucumber. It also applies to you if
+you're developing a 3rd party tool that integrates with Cucumber.
+
+== Internal API
+
+Cucumber has more classes, modules and methods than what you can see in the public
+API. If you decide to dive into the source code and make use of an API that isn't
+part of this documentation - beware that this API might change at any time. If you
+want a particular internal API to be promoted to the public API - let us know.
2  lib/cucumber/ast/background.rb
View
@@ -2,7 +2,7 @@
module Cucumber
module Ast
- class Background
+ class Background #:nodoc:
include FeatureElement
attr_reader :feature_elements
2  lib/cucumber/ast/comment.rb
View
@@ -7,7 +7,7 @@ module Ast
#
# This gets parsed into a Comment with value <tt>"# Lorem ipsum\n# dolor sit amet\n"</tt>
#
- class Comment
+ class Comment #:nodoc:
def initialize(value)
@value = value
end
2  lib/cucumber/ast/examples.rb
View
@@ -1,6 +1,6 @@
module Cucumber
module Ast
- class Examples
+ class Examples #:nodoc:
def initialize(line, keyword, name, outline_table)
@keyword, @name, @outline_table = keyword, name, outline_table
end
2  lib/cucumber/ast/feature.rb
View
@@ -1,7 +1,7 @@
module Cucumber
module Ast
# Represents the root node of a parsed feature.
- class Feature
+ class Feature #:nodoc:
attr_accessor :file, :language
attr_writer :features
attr_reader :name
2  lib/cucumber/ast/feature_element.rb
View
@@ -1,7 +1,7 @@
require 'enumerator'
module Cucumber
- module FeatureElement
+ module FeatureElement #:nodoc:
attr_writer :feature
def attach_steps(steps)
2  lib/cucumber/ast/features.rb
View
@@ -1,6 +1,6 @@
module Cucumber
module Ast
- class Features
+ class Features #:nodoc:
include Enumerable
attr_reader :duration
4 lib/cucumber/ast/outline_table.rb
View
@@ -1,6 +1,6 @@
module Cucumber
module Ast
- class OutlineTable < Table
+ class OutlineTable < Table #:nodoc:
def initialize(raw, scenario_outline)
super(raw)
@scenario_outline = scenario_outline
@@ -44,7 +44,7 @@ def visit_scenario_name(visitor, row)
@scenario_outline.visit_scenario_name(visitor, row)
end
- class ExampleRow < Cells
+ class ExampleRow < Cells #:nodoc:
attr_reader :scenario_outline # https://rspec.lighthouseapp.com/projects/16211/tickets/342
def create_step_invocations!(scenario_outline)
2  lib/cucumber/ast/py_string.rb
View
@@ -16,7 +16,7 @@ module Ast
#
# Note how the indentation from the source is stripped away.
#
- class PyString
+ class PyString #:nodoc:
def self.default_arg_name
"string"
end
2  lib/cucumber/ast/scenario.rb
View
@@ -2,7 +2,7 @@
module Cucumber
module Ast
- class Scenario
+ class Scenario #:nodoc:
include FeatureElement
attr_reader :name, :line
4 lib/cucumber/ast/scenario_outline.rb
View
@@ -1,9 +1,9 @@
module Cucumber
module Ast
- class ScenarioOutline
+ class ScenarioOutline #:nodoc:
include FeatureElement
- module ExamplesArray
+ module ExamplesArray #:nodoc:
def accept(visitor)
return if $cucumber_interrupted
each do |examples|
2  lib/cucumber/ast/step.rb
View
@@ -3,7 +3,7 @@
module Cucumber
module Ast
- class Step
+ class Step #:nodoc:
attr_reader :line, :keyword, :name, :multiline_arg
attr_writer :step_collection, :options
attr_accessor :feature_element, :exception
2  lib/cucumber/ast/step_collection.rb
View
@@ -1,7 +1,7 @@
module Cucumber
module Ast
# Holds an Array of Step or StepDefinition
- class StepCollection
+ class StepCollection #:nodoc:
include Enumerable
def initialize(steps)
2  lib/cucumber/ast/step_invocation.rb
View
@@ -2,7 +2,7 @@
module Cucumber
module Ast
- class StepInvocation
+ class StepInvocation #:nodoc:
attr_writer :step_collection, :background
attr_reader :name, :matched_cells, :status, :reported_exception
attr_accessor :exception
104 lib/cucumber/ast/table.rb
View
@@ -1,11 +1,23 @@
module Cucumber
module Ast
- # Holds the data of a table parsed from a feature file:
+ # 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.
#
- # | a | b |
- # | c | d |
+ # For example:
#
- # This gets parsed into a Table holding the values <tt>[['a', 'b'], ['c', 'd']]</tt>
+ # Given I have:
+ # | a | b |
+ # | c | d |
+ #
+ # And a matching StepDefinition:
+ #
+ # Given /I have:/ do |table|
+ # data = table.raw
+ # end
+ #
+ # This will store <tt>[['a', 'b'], ['c', 'd']]</tt> in the <tt>data</tt> variable.
#
class Table
include Enumerable
@@ -14,10 +26,14 @@ class Table
attr_accessor :file
- def self.default_arg_name
+ def self.default_arg_name #:nodoc:
"table"
end
+ # Creates a new instance. +raw+ should be an Array of Array of String.
+ # You don't typically create your own Table objects - Cucumber will do
+ # it internally and pass them to your Step Definitions.
+ #
def initialize(raw, conversion_procs = NULL_CONVERSIONS.dup)
@cells_class = Cells
@cell_class = Cell
@@ -28,21 +44,23 @@ def initialize(raw, conversion_procs = NULL_CONVERSIONS.dup)
@conversion_procs = conversion_procs
end
- # Creates a copy of this table, inheriting the column mappings.
+ # Creates a copy of this table, inheriting any column mappings.
+ # registered with #map_headers!
+ #
def dup
self.class.new(raw.dup, @conversion_procs.dup)
end
# Returns a new, transposed table. Example:
#
- # | a | 7 | 4 |
- # | b | 9 | 2 |
+ # | a | 7 | 4 |
+ # | b | 9 | 2 |
#
# Gets converted into the following:
#
- # | a | b |
- # | 7 | 9 |
- # | 4 | 2 |
+ # | a | b |
+ # | 7 | 9 |
+ # | 4 | 2 |
#
def transpose
self.class.new(raw.transpose, @conversion_procs.dup)
@@ -109,11 +127,11 @@ def rows
raw[1..-1]
end
- def each_cells_row(&proc)
+ def each_cells_row(&proc) #:nodoc:
cells_rows.each(&proc)
end
- def accept(visitor)
+ def accept(visitor) #:nodoc:
return if $cucumber_interrupted
cells_rows.each do |row|
visitor.visit_table_row(row)
@@ -206,10 +224,10 @@ def map_column!(column_name, strict=true, &conversion_proc)
# Whether to raise or not raise can be changed by setting values in
# +options+ to true or false:
#
- # * <tt>missing_row</tt>: Raise on missing rows (defaults to true)
- # * <tt>surplus_row</tt>: Raise on surplus rows (defaults to true)
- # * <tt>missing_col</tt>: Raise on missing columns (defaults to true)
- # * <tt>surplus_col</tt>: Raise on surplus columns (defaults to false)
+ # * <tt>missing_row</tt> : Raise on missing rows (defaults to true)
+ # * <tt>surplus_row</tt> : Raise on surplus rows (defaults to true)
+ # * <tt>missing_col</tt> : Raise on missing columns (defaults to true)
+ # * <tt>surplus_col</tt> : 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).
@@ -298,11 +316,11 @@ def index(cells) #:nodoc:
cells_rows.index(cells)
end
- def verify_column(column_name)
+ def verify_column(column_name) #:nodoc:
raise %{The column named "#{column_name}" does not exist} unless raw[0].include?(column_name)
end
- def verify_table_width(width)
+ def verify_table_width(width) #:nodoc:
raise %{The table must have exactly #{width} columns} unless raw[0].size == width
end
@@ -321,33 +339,33 @@ def arguments_replaced(arguments) #:nodoc:
Table.new(raw_with_replaced_args)
end
- def has_text?(text)
+ def has_text?(text) #:nodoc:
raw.flatten.compact.detect{|cell_value| cell_value.index(text)}
end
- def cells_rows
+ def cells_rows #:nodoc:
@rows ||= cell_matrix.map do |cell_row|
@cells_class.new(self, cell_row)
end
end
- def headers
+ def headers #:nodoc:
raw.first
end
- def header_cell(col)
+ def header_cell(col) #:nodoc:
cells_rows[0][col]
end
- def cell_matrix
+ def cell_matrix #:nodoc:
@cell_matrix
end
- def col_width(col)
+ def col_width(col) #:nodoc:
columns[col].__send__(:width)
end
- def to_s(options = {})
+ def to_s(options = {}) #:nodoc:
options = {:color => true, :indent => 2, :prefixes => TO_S_PREFIXES}.merge(options)
io = StringIO.new
@@ -371,7 +389,7 @@ def to_s(options = {})
protected
- def inspect_rows(missing_row, inserted_row)
+ def inspect_rows(missing_row, inserted_row) #:nodoc:
missing_row.each_with_index do |missing_cell, col|
inserted_cell = inserted_row[col]
if(missing_cell.value != inserted_cell.value && (missing_cell.value.to_s == inserted_cell.value.to_s))
@@ -381,7 +399,7 @@ def inspect_rows(missing_row, inserted_row)
end
end
- def create_cell_matrix(raw)
+ def create_cell_matrix(raw) #:nodoc:
@cell_matrix = raw.map do |raw_row|
line = raw_row.line rescue -1
raw_row.map do |raw_cell|
@@ -390,7 +408,7 @@ def create_cell_matrix(raw)
end
end
- def convert_columns!
+ def convert_columns! #:nodoc:
cell_matrix.transpose.each do |col|
conversion_proc = @conversion_procs[col[0].value]
col[1..-1].each do |cell|
@@ -399,7 +417,7 @@ def convert_columns!
end
end
- def require_diff_lcs
+ def require_diff_lcs #:nodoc:
begin
require 'diff/lcs'
rescue LoadError => e
@@ -408,23 +426,23 @@ def require_diff_lcs
end
end
- def clear_cache!
+ def clear_cache! #:nodoc:
@hashes = @rows_hash = @rows = @columns = nil
end
- def columns
+ def columns #:nodoc:
@columns ||= cell_matrix.transpose.map do |cell_row|
@cells_class.new(self, cell_row)
end.freeze
end
- def new_cell(raw_cell, line)
+ def new_cell(raw_cell, line) #:nodoc:
@cell_class.new(raw_cell, self, line)
end
# Pads our own cell_matrix and returns a cell matrix of same
# column width that can be used for diffing
- def pad!(other_cell_matrix)
+ def pad!(other_cell_matrix) #:nodoc:
clear_cache!
cols = cell_matrix.transpose
unmapped_cols = other_cell_matrix.transpose
@@ -462,38 +480,38 @@ def pad!(other_cell_matrix)
(mapped_cols + unmapped_cols).transpose
end
- def ensure_table(table_or_array)
+ def ensure_table(table_or_array) #:nodoc:
return table_or_array if Table === table_or_array
table_or_array = hashes_to_array(table_or_array) if Hash === table_or_array[0]
table_or_array = enumerable_to_array(table_or_array) unless Array == table_or_array[0]
Table.new(table_or_array)
end
- def hashes_to_array(hashes)
+ def hashes_to_array(hashes) #:nodoc:
header = hashes[0].keys
[header] + hashes.map{|hash| header.map{|key| hash[key]}}
end
- def enumerable_to_array(rows)
+ def enumerable_to_array(rows) #:nodoc:
rows.map{|row| row.map{|cell| cell}}
end
- def ensure_green!
+ def ensure_green! #:nodoc:
each_cell{|cell| cell.status = :passed}
end
- def each_cell(&proc)
+ def each_cell(&proc) #:nodoc:
cell_matrix.each{|row| row.each(&proc)}
end
- def mark_as_missing(col)
+ def mark_as_missing(col) #:nodoc:
col.each do |cell|
cell.status = :undefined
end
end
# Represents a row of cells or columns of cells
- class Cells
+ class Cells #:nodoc:
include Enumerable
attr_reader :exception
@@ -549,7 +567,7 @@ def each(&proc)
end
end
- class Cell
+ class Cell #:nodoc:
attr_reader :line, :table
attr_accessor :status, :value
@@ -576,7 +594,7 @@ def to_sexp #:nodoc:
end
end
- class SurplusCell < Cell
+ class SurplusCell < Cell #:nodoc:
def status
:comment
end
2  lib/cucumber/ast/tags.rb
View
@@ -6,7 +6,7 @@ module Ast
#
# This gets stored internally as <tt>["invoice", "release_2"]</tt>
#
- class Tags
+ class Tags #:nodoc:
def self.strip_prefix(tag_name)
tag_name =~ /^@(.*)/ ? $1 : tag_name
end
14 lib/cucumber/ast/visitor.rb
View
@@ -1,20 +1,17 @@
module Cucumber
module Ast
- # A dumb visitor that implements the whole Visitor API and just walks the tree.
+ # Base class for formatters. This class just walks the tree depth first.
+ # Just override the methods you care about. Remember to call super if you
+ # override a method.
class Visitor
- attr_accessor :options
- attr_reader :step_mother
+ attr_accessor :options #:nodoc:
+ attr_reader :step_mother #:nodoc:
def initialize(step_mother)
@options = {}
@step_mother = step_mother
end
- def matches_scenario_names?(node)
- scenario_name_regexps = options[:name_regexps] || []
- scenario_name_regexps.empty? || node.matches_scenario_names?(scenario_name_regexps)
- end
-
def visit_features(features)
features.accept(self)
end
@@ -109,6 +106,7 @@ def visit_table_cell(table_cell)
def visit_table_cell_value(value, status)
end
+ # Print +announcement+. This method can be called from within StepDefinitions.
def announce(announcement)
end
2  lib/cucumber/broadcaster.rb
View
@@ -1,5 +1,5 @@
module Cucumber
- class Broadcaster
+ class Broadcaster #:nodoc:
def initialize(receivers = [])
@receivers = receivers
end
2  lib/cucumber/constantize.rb
View
@@ -1,5 +1,5 @@
module Cucumber
- module Constantize
+ module Constantize #:nodoc:
def constantize(camel_cased_word)
begin
names = camel_cased_word.split('::')
2  lib/cucumber/core_ext/exception.rb
View
@@ -18,7 +18,7 @@
#
# All backtrace munging can be turned off with the <tt>--backtrace</tt> switch
#
-class Exception
+class Exception #:nodoc:
CUCUMBER_FILTER_PATTERNS = [
/vendor\/rails|lib\/cucumber|bin\/cucumber:|lib\/rspec|gems\//
]
11 lib/cucumber/core_ext/instance_exec.rb
View
@@ -1,11 +1,13 @@
require 'cucumber/platform'
module Cucumber
+ # Raised if the number of a StepDefinition's Regexp match groups
+ # is different from the number of Proc arguments.
class ArityMismatchError < StandardError
end
end
-class Object
+class Object #:nodoc:
def cucumber_instance_exec(check_arity, pseudo_method, *args, &block)
cucumber_run_with_backtrace_filtering(pseudo_method) do
if check_arity && !cucumber_compatible_arity?(args, block)
@@ -23,7 +25,9 @@ def cucumber_instance_exec(check_arity, pseudo_method, *args, &block)
end
end
end
-
+
+ private
+
def cucumber_arity(block)
a = block.arity
Cucumber::RUBY_1_9 ? a : (a == -1 ? 0 : a)
@@ -48,7 +52,8 @@ def cucumber_run_with_backtrace_filtering(pseudo_method)
unless defined? instance_exec # 1.9
# http://eigenclass.org/hiki/bounded+space+instance_exec
- module InstanceExecHelper; end
+ module InstanceExecHelper #:nodoc:
+ end
include InstanceExecHelper
def instance_exec(*args, &block)
begin
2  lib/cucumber/core_ext/proc.rb
View
@@ -1,5 +1,5 @@
# Proc extension to get more location info out of a proc
-class Proc
+class Proc #:nodoc:
PROC_PATTERN = /[\d\w]+@(.*):(.*)>/
def to_comment_line
2  lib/cucumber/core_ext/string.rb
View
@@ -1,4 +1,4 @@
-class String
+class String #:nodoc:
def indent(n)
if n >= 0
gsub(/^/, ' ' * n)
7 lib/cucumber/feature_file.rb
View
@@ -3,10 +3,11 @@
module Cucumber
class FeatureFile
- FILE_COLON_LINE_PATTERN = /^([\w\W]*?):([\d:]+)$/
- LANGUAGE_PATTERN = /language:\s*(.*)/
+ FILE_COLON_LINE_PATTERN = /^([\w\W]*?):([\d:]+)$/ #:nodoc:
+ LANGUAGE_PATTERN = /language:\s*(.*)/ #:nodoc:
- # The +uri+ argument can ba a path or a path:line1:line2 etc.
+ # The +uri+ argument is the location of the source. It can ba a path
+ # or a path:line1:line2 etc. If +source+ is passed, +uri+ is ignored.
def initialize(uri, source=nil)
@source = source
_, @path, @lines = *FILE_COLON_LINE_PATTERN.match(uri)
3  lib/cucumber/filter.rb
View
@@ -1,5 +1,6 @@
module Cucumber
- class Filter
+ # Filters the AST based on --tags and --name
+ class Filter #:nodoc:
def initialize(lines, options)
@lines = lines
11 lib/cucumber/formatter/ansicolor.rb
View
@@ -23,8 +23,9 @@
module Cucumber
module Formatter
- # Defines aliases for coloured output. You can tweak the colours by defining
- # a <tt>CUCUMBER_COLORS</tt> variable in your shell, very much like you can
+ # Defines aliases for coloured output. You don't invoke any methods from this
+ # module directly, but you can change the output colours by defining
+ # a <tt>CUCUMBER_COLORS</tt> variable in your shell, very much like how you can
# tweak the familiar POSIX command <tt>ls</tt> with
# <a href="http://mipsisrisc.com/rambling/2008/06/27/lscolorsls_colors-now-with-linux-support/">$LSCOLORS/$LS_COLORS</a>
#
@@ -97,7 +98,7 @@ def #{method}_param(string=nil, &proc)
end
end
- def self.define_grey
+ def self.define_grey #:nodoc:
begin
gem 'genki-ruby-terminfo'
require 'terminfo'
@@ -125,8 +126,8 @@ def self.define_grey
end
end
- def self.define_real_grey
- def grey(m)
+ def self.define_real_grey #:nodoc:
+ def grey(m) #:nodoc:
if ::Term::ANSIColor.coloring?
"\e[90m#{m}\e[0m"
else
2  lib/cucumber/formatter/color_io.rb
View
@@ -3,7 +3,7 @@
module Cucumber
module Formatter
# Adapter to make #puts/#print/#flush work with colours on Windows
- class ColorIO
+ class ColorIO #:nodoc:
extend Forwardable
def_delegators :@kernel, :puts, :print # win32console colours only work when sent to Kernel
def_delegators :@stdout, :flush, :tty?, :write
2  lib/cucumber/formatter/console.rb
View
@@ -3,6 +3,8 @@
module Cucumber
module Formatter
+ # This module contains helper methods that are used by formatters
+ # that print output to the terminal.
module Console
extend ANSIColor
include Duration
3  lib/cucumber/formatter/duration.rb
View
@@ -1,6 +1,9 @@
module Cucumber
module Formatter
module Duration
+ # Helper method for formatters that need to
+ # format a duration in seconds to the UNIX
+ # <tt>time</tt> format.
def format_duration(seconds)
m, s = seconds.divmod(60)
"#{m}m#{'%.3f' % s}s"
1  lib/cucumber/formatter/html.rb
View
@@ -3,6 +3,7 @@
module Cucumber
module Formatter
+ # The formatter used for <tt>--format html</tt>
class Html < Ast::Visitor
include ERB::Util # for the #h method
include Duration
1  lib/cucumber/formatter/junit.rb
View
@@ -2,6 +2,7 @@
module Cucumber
module Formatter
+ # The formatter used for <tt>--format junit</tt>
class Junit < Cucumber::Ast::Visitor
def initialize(step_mother, io, options)
2  lib/cucumber/formatter/ordered_xml_markup.rb
View
@@ -8,7 +8,7 @@
module Cucumber
module Formatter
# Emits attributes ordered alphabetically, so that we can predicatbly test output.
- class OrderedXmlMarkup < Builder::XmlMarkup
+ class OrderedXmlMarkup < Builder::XmlMarkup #:nodoc:
def _insert_attributes(attrs, order=[])
return if attrs.nil?
keys = attrs.keys.map{|k| k.to_s}
2  lib/cucumber/formatter/pretty.rb
View
@@ -3,6 +3,8 @@
module Cucumber
module Formatter
+ # The formatter used for <tt>--format pretty</tt> (the default formatter).
+ #
# This formatter prints features to plain text - exactly how they were parsed,
# just prettier. That means with proper indentation and alignment of table columns.
#
1  lib/cucumber/formatter/profile.rb
View
@@ -2,6 +2,7 @@
module Cucumber
module Formatter
+ # The formatter used for <tt>--format profile</tt>
class Profile < Progress
NUMBER_OF_STEP_DEFINITONS_TO_SHOW = 10
NUMBER_OF_STEP_INVOCATIONS_TO_SHOW = 5
1  lib/cucumber/formatter/progress.rb
View
@@ -2,6 +2,7 @@
module Cucumber
module Formatter
+ # The formatter used for <tt>--format progress</tt>
class Progress < Ast::Visitor
include Console
2  lib/cucumber/formatter/rerun.rb
View
@@ -1,5 +1,7 @@
module Cucumber
module Formatter
+ # The formatter used for <tt>--format rerun</tt>
+ #
# This formatter keeps track of all failing features and print out their location.
# Example:
#
1  lib/cucumber/formatter/steps.rb
View
@@ -1,5 +1,6 @@
module Cucumber
module Formatter
+ # The formatter used for <tt>--format steps</tt>
class Steps < Ast::Visitor
def initialize(step_mother, io, options)
3  lib/cucumber/formatter/tag_cloud.rb
View
@@ -1,6 +1,7 @@
module Cucumber
module Formatter
- # Custom formatter that prints a tag cloud
+ # The formatter used for <tt>--format tag_cloud</tt>
+ # Custom formatter that prints a tag cloud as a table.
class TagCloud < Cucumber::Ast::Visitor
def initialize(step_mother, io, options)
super(step_mother)
2  lib/cucumber/formatter/unicode.rb
View
@@ -12,7 +12,7 @@
Cucumber::CODEPAGE = "cp#{codepage}"
require 'iconv'
- module Kernel
+ module Kernel #:nodoc:
alias cucumber_print print
def print(*a)
begin
1  lib/cucumber/formatter/usage.rb
View
@@ -2,6 +2,7 @@
module Cucumber
module Formatter
+ # The formatter used for <tt>--format usage</tt>
class Usage < Ast::Visitor
include Console
11 lib/cucumber/parser/treetop_ext.rb
View
@@ -12,6 +12,7 @@
module Cucumber
module Parser
+ # Raised if Cucumber fails to parse a feature file
class SyntaxError < StandardError
def initialize(parser, file, line_offset)
tf = parser.terminal_failures
@@ -22,7 +23,7 @@ def initialize(parser, file, line_offset)
end
end
- module TreetopExt
+ module TreetopExt #:nodoc:
def parse_or_fail(source, file=nil, filter=nil, line_offset=0)
parse_tree = parse(source)
if parse_tree.nil?
@@ -37,15 +38,15 @@ def parse_or_fail(source, file=nil, filter=nil, line_offset=0)
end
end
-module Treetop
- module Runtime
- class SyntaxNode
+module Treetop #:nodoc:
+ module Runtime #:nodoc:
+ class SyntaxNode #:nodoc:
def line
input.line_of(interval.first)
end
end
- class CompiledParser
+ class CompiledParser #:nodoc:
include Cucumber::Parser::TreetopExt
end
end
3  lib/cucumber/platform.rb
View
@@ -4,7 +4,6 @@
require 'yaml'
module Cucumber
- # TODO: Move these constants and the file to Language. Update wiki
LANGUAGE_FILE = File.expand_path(File.dirname(__FILE__) + '/languages.yml')
LANGUAGES = YAML.load_file(LANGUAGE_FILE)
BINARY = File.expand_path(File.dirname(__FILE__) + '/../../bin/cucumber')
@@ -17,7 +16,7 @@ module Cucumber
RUBY_BINARY = File.join(Config::CONFIG['bindir'], Config::CONFIG['ruby_install_name'])
RUBY_1_9 = RUBY_VERSION =~ /^1\.9/
- def self.file_mode(m)
+ def self.file_mode(m) #:nodoc:
RUBY_1_9 ? "#{m}:UTF-8" : m
end
end
3  lib/cucumber/rails/world.rb
View
@@ -23,7 +23,8 @@
module Cucumber #:nodoc:
module Rails
- # All scenarios will execute in the context of a new instance of World.
+ # All scenarios will execute in the context of a new instance of Cucumber::Rails:World if this file
+ # is loaded. This gives Step Definitions access to all the methods from Rails' ActionController::IntegrationTest
class World < ActionController::IntegrationTest
if defined?(ActiveRecord::Base)
self.use_transactional_fixtures = false
24 lib/cucumber/rake/task.rb
View
@@ -8,7 +8,7 @@ module Rake
#
# Cucumber::Rake::Task.new
#
- # This will create a task named 'cucumber' described as 'Run Cucumber features'.
+ # This will define a task named <tt>cucumber</tt> described as 'Run Cucumber features'.
# It will use steps from 'features/**/*.rb' and features in 'features/**/*.feature'.
#
# To further configure the task, you can pass a block:
@@ -82,10 +82,10 @@ def initialize(libs, cucumber_bin, cucumber_opts, feature_files, rcov_opts)
end
end
- LIB = File.expand_path(File.dirname(__FILE__) + '/../..') # :nodoc:
+ LIB = File.expand_path(File.dirname(__FILE__) + '/../..') #:nodoc:
# TODO: remove depreated accessors for 0.4.0
- def self.deprecate_accessor(attribute) # :nodoc:
+ def self.deprecate_accessor(attribute) #:nodoc:
attr_reader attribute
class_eval <<-EOF, __FILE__, __LINE__ + 1
def #{attribute}=(value)
@@ -133,7 +133,9 @@ def rcov_opts=(opts) #:nodoc:
@rcov_opts = String === opts ? opts.split(' ') : opts
end
- # Whether or not to fork a new ruby interpreter. Defaults to true.
+ # Whether or not to fork a new ruby interpreter. Defaults to true. You may gain
+ # some startup speed if you set it to false, but this may also cause issues with
+ # your load path and gems.
attr_accessor :fork
# Define what profile to be used. When used with cucumber_opts it is simply appended to it. Will be ignored when CUCUMBER_OPTS is used.
@@ -165,14 +167,14 @@ def initialize(task_name = "cucumber", desc = "Run Cucumber features")
define_task
end
- def define_task # :nodoc:
+ def define_task #:nodoc:
desc @desc
task @task_name do
runner.run
end
end
- def runner(task_args = nil) # :nodoc:
+ def runner(task_args = nil) #:nodoc:
cucumber_opts = [(ENV['CUCUMBER_OPTS'] ? ENV['CUCUMBER_OPTS'].split(/\s+/) : nil) || cucumber_opts_with_profile]
if(@rcov)
RCovCucumberRunner.new(libs, binary, cucumber_opts, feature_files(task_args), rcov_opts)
@@ -183,11 +185,11 @@ def runner(task_args = nil) # :nodoc:
end
end
- def cucumber_opts_with_profile # :nodoc:
+ def cucumber_opts_with_profile #:nodoc:
@profile ? [cucumber_opts, '--profile', @profile] : cucumber_opts
end
- def feature_files(task_args = nil) # :nodoc:
+ def feature_files(task_args = nil) #:nodoc:
if ENV['FEATURE']
FileList[ ENV['FEATURE'] ]
else
@@ -199,7 +201,7 @@ def feature_files(task_args = nil) # :nodoc:
end
end
- def step_files(task_args = nil) # :nodoc:
+ def step_files(task_args = nil) #:nodoc:
if ENV['STEPS']
FileList[ ENV['STEPS'] ]
else
@@ -222,14 +224,14 @@ def initialize(task_name = "feature", desc = "Run a specified feature with Cucum
super(task_name, desc)
end
- def define_task # :nodoc:
+ def define_task #:nodoc:
desc @desc
task @task_name, :feature_name do |t, args|
runner(args).run
end
end
- def feature_files(task_arguments) # :nodoc:
+ def feature_files(task_arguments) #:nodoc:
FileList[File.join("features", "**", "#{task_arguments[:feature_name]}.feature")]
end
18 lib/cucumber/rb_support/rb_dsl.rb
View
@@ -36,31 +36,31 @@ def World(*world_modules, &proc)
RbDsl.rb_language.build_world_factory(*world_modules, &proc)
end
- # Registers a Before proc. You can call this method as many times as you
- # want (typically from ruby scripts under <tt>support</tt>).
+ # Registers a proc that will run before each Scenario. You can register as
+ # as you want (typically from ruby scripts under <tt>support/hooks.rb</tt>).
def Before(*tag_names, &proc)
RbDsl.step_mother.register_hook(:before, RbHook.new(RbDsl.rb_language, tag_names, proc))
end
+ # Registers a proc that will run after each Scenario. You can register as
+ # as you want (typically from ruby scripts under <tt>support/hooks.rb</tt>).
def After(*tag_names, &proc)
RbDsl.step_mother.register_hook(:after, RbHook.new(RbDsl.rb_language, tag_names, proc))
end
+ # Registers a proc that will run after each Step. You can register as
+ # as you want (typically from ruby scripts under <tt>support/hooks.rb</tt>).
def AfterStep(*tag_names, &proc)
RbDsl.step_mother.register_hook(:after_step, RbHook.new(RbDsl.rb_language, tag_names, proc))
end
- # Registers a new Ruby StepDefinition.
- # This method is aliased
+ # Registers a new Ruby StepDefinition. This method is aliased
# to <tt>Given</tt>, <tt>When</tt> and <tt>Then</tt>, and
# also to the i18n translations whenever a feature of a
# new language is loaded.
#
- # See Cucumber#alias_steps for details on how to
- # create your own aliases.
- #
- # The +&proc+ gets executed in the context of a <tt>world</tt>
- # object, which is defined by #World. A new <tt>world</tt>
+ # The +&proc+ gets executed in the context of a <tt>World</tt>
+ # object, which is defined by #World. A new <tt>World</tt>
# object is created for each scenario and is shared across
# step definitions within that scenario.
def register_rb_step_definition(regexp, &proc)
1  lib/cucumber/rb_support/rb_hook.rb
View
@@ -1,5 +1,6 @@
module Cucumber
module RbSupport
+ # Wrapper for Before, After and AfterStep hooks
class RbHook
include LanguageSupport::HookMethods
3  lib/cucumber/rb_support/rb_language.rb
View
@@ -3,12 +3,14 @@
module Cucumber
module RbSupport
+ # Raised if a World block returns Nil.
class NilWorld < StandardError
def initialize
super("World procs should never return nil")
end
end
+ # Raised if there are 2 or more World blocks.
class MultipleWorld < StandardError
def initialize(first_proc, second_proc)
message = "You can only pass a proc to #World once, but it's happening\n"
@@ -21,6 +23,7 @@ def initialize(first_proc, second_proc)
end
end
+ # The Ruby implementation of the programming language API.
class RbLanguage
include LanguageSupport::LanguageMethods
attr_reader :current_world, :step_mother
6 lib/cucumber/rb_support/rb_step_definition.rb
View
@@ -3,9 +3,11 @@
require 'cucumber/core_ext/proc'
module Cucumber
- # A Step Definition holds a Regexp and a Proc, and is created
+ # A Ruby Step Definition holds a Regexp and a Proc, and is created
# by calling <tt>Given</tt>, <tt>When</tt> or <tt>Then</tt>
- # in the <tt>step_definitions</tt> ruby files - for example:
+ # in the <tt>step_definitions</tt> ruby files. See also RbDsl.
+ #
+ # Example:
#
# Given /I have (\d+) cucumbers in my belly/ do
# # some code here
6 lib/cucumber/rspec_neuter.rb
View
@@ -1,11 +1,11 @@
require 'optparse'
-module Spec
- module Runner
+module Spec #:nodoc:
+ module Runner #:nodoc:
# Neuters RSpec's option parser.
# (RSpec's option parser tries to parse ARGV, which
# will fail when running cucumber)
- class OptionParser < ::OptionParser
+ class OptionParser < ::OptionParser #:nodoc:
NEUTERED_RSPEC = Object.new
def NEUTERED_RSPEC.method_missing(m, *args); self; end
4 lib/cucumber/step_match.rb
View
@@ -1,5 +1,5 @@
module Cucumber
- class StepMatch
+ class StepMatch #:nodoc:
attr_reader :step_definition, :args
def initialize(step_definition, step_name, formatted_step_name, args)
@@ -33,7 +33,7 @@ def text_length
end
end
- class NoStepMatch
+ class NoStepMatch #:nodoc:
attr_reader :step_definition, :name
def initialize(step, name)
55 lib/cucumber/step_mother.rb
View
@@ -7,6 +7,7 @@
require 'cucumber/language_support/step_definition_methods'
module Cucumber
+ # Raised when there is no matching StepDefinition for a step.
class Undefined < StandardError
attr_reader :step_name
@@ -28,7 +29,7 @@ def nested?
class Pending < StandardError
end
- # Raised when a step matches 2 or more StepDefinition
+ # Raised when a step matches 2 or more StepDefinitions
class Ambiguous < StandardError
def initialize(step_name, step_definitions, used_guess)
message = "Ambiguous match of \"#{step_name}\":\n\n"
@@ -49,10 +50,7 @@ def initialize(step_def_1, step_def_2)
end
end
- # This is the main interface for registering step definitions, which is done
- # from <tt>*_steps.rb</tt> files. This module is included right at the top-level
- # so #register_step_definition (and more interestingly - its aliases) are
- # available from the top-level.
+ # This is the meaty part of Cucumber that ties everything together.
class StepMother
include Constantize
@@ -68,8 +66,6 @@ def initialize
# Instances are cached, so calling with the same argument
# twice will return the same instance.
#
- # Raises an exception if the language can't be loaded.
- #
def load_programming_language(ext)
return @language_map[ext] if @language_map[ext]
programming_language_class = constantize("Cucumber::#{ext.capitalize}Support::#{ext.capitalize}Language")
@@ -99,15 +95,16 @@ def register_step_definition(step_definition)
step_definition
end
+ # Returns the options passed on the command line.
def options
@options ||= {}
end
- def step_visited(step)
+ def step_visited(step) #:nodoc:
steps << step unless steps.index(step)
end
-
- def steps(status = nil)
+
+ def steps(status = nil) #:nodoc:
@steps ||= []
if(status)
@steps.select{|step| step.status == status}
@@ -116,11 +113,11 @@ def steps(status = nil)
end
end
- def announce(msg)
+ def announce(msg) #:nodoc:
@visitor.announce(msg)
end
- def scenarios(status = nil)
+ def scenarios(status = nil) #:nodoc:
@scenarios ||= []
if(status)
@scenarios.select{|scenario| scenario.status == status}
@@ -129,20 +126,20 @@ def scenarios(status = nil)
end
end
- def register_hook(phase, hook)
+ def register_hook(phase, hook) #:nodoc:
hooks[phase.to_sym] << hook
hook
end
- def hooks
+ def hooks #:nodoc:
@hooks ||= Hash.new {|hash, phase| hash[phase] = []}
end
- def hooks_for(phase, scenario)
+ def hooks_for(phase, scenario) #:nodoc:
hooks[phase.to_sym].select{|hook| scenario.accept_hook?(hook)}
end
- def step_match(step_name, formatted_step_name=nil)
+ def step_match(step_name, formatted_step_name=nil) #:nodoc:
matches = step_definitions.map { |d| d.step_match(step_name, formatted_step_name) }.compact
raise Undefined.new(step_name) if matches.empty?
matches = best_matches(step_name, matches) if matches.size > 1 && options[:guess]
@@ -150,7 +147,7 @@ def step_match(step_name, formatted_step_name=nil)
matches[0]
end
- def best_matches(step_name, step_matches)
+ def best_matches(step_name, step_matches) #:nodoc:
no_groups = step_matches.select {|step_match| step_match.args.length == 0}
max_arg_length = step_matches.map {|step_match| step_match.args.length }.max
top_groups = step_matches.select {|step_match| step_match.args.length == max_arg_length }
@@ -166,31 +163,31 @@ def best_matches(step_name, step_matches)
end
end
- def clear!
+ def clear! #:nodoc:
step_definitions.clear
hooks.clear
steps.clear
scenarios.clear
end
- def step_definitions
+ def step_definitions #:nodoc:
@step_definitions ||= []
end
- def snippet_text(step_keyword, step_name, multiline_arg_class)
+ def snippet_text(step_keyword, step_name, multiline_arg_class) #:nodoc:
@programming_languages.map do |programming_language|
programming_language.snippet_text(step_keyword, step_name, multiline_arg_class)
end.join("\n")
end
- def before_and_after(scenario, skip_hooks=false)
+ def before_and_after(scenario, skip_hooks=false) #:nodoc:
before(scenario) unless skip_hooks
yield scenario
after(scenario) unless skip_hooks
scenario_visited(scenario)
end
- def register_adverbs(adverbs)
+ def register_adverbs(adverbs) #:nodoc:
@adverbs ||= []
@adverbs += adverbs
@adverbs.uniq!
@@ -199,21 +196,21 @@ def register_adverbs(adverbs)
end
end
- def begin_scenario
+ def begin_scenario #:nodoc:
return if options[:dry_run]
@programming_languages.each do |programming_language|
programming_language.begin_scenario
end
end
- def end_scenario
+ def end_scenario #:nodoc:
return if options[:dry_run]
@programming_languages.each do |programming_language|
programming_language.end_scenario
end
end
- def before(scenario)
+ def before(scenario) #:nodoc:
return if options[:dry_run] || @current_scenario
@current_scenario = scenario
@programming_languages.each do |programming_language|
@@ -221,7 +218,7 @@ def before(scenario)
end
end
- def after(scenario)
+ def after(scenario) #:nodoc:
@current_scenario = nil
return if options[:dry_run]
@programming_languages.each do |programming_language|
@@ -229,7 +226,7 @@ def after(scenario)
end
end
- def after_step
+ def after_step #:nodoc:
return if options[:dry_run]
@programming_languages.each do |programming_language|
programming_language.execute_after_step(@current_scenario)
@@ -238,11 +235,11 @@ def after_step
private
- def max_step_definition_length
+ def max_step_definition_length #:nodoc:
@max_step_definition_length ||= step_definitions.map{|step_definition| step_definition.text_length}.max
end
- def scenario_visited(scenario)
+ def scenario_visited(scenario) #:nodoc:
scenarios << scenario unless scenarios.index(scenario)
end
end
2  lib/cucumber/version.rb
View
@@ -3,7 +3,7 @@ class VERSION #:nodoc:
MAJOR = 0
MINOR = 3
TINY = 96
- PATCH = nil # Set to nil for official release
+ PATCH = 1 # Set to nil for official release
STRING = [MAJOR, MINOR, TINY, PATCH].compact.join('.')
end
6 lib/cucumber/webrat/element_locator.rb
View
@@ -55,7 +55,7 @@ def table_from_list #:nodoc:
end
module Locators
- class ElementLocator < Locator
+ class ElementLocator < Locator #:nodoc:
def locate
Element.load(@session, table_element)
end
@@ -77,11 +77,11 @@ def element_at(css_selector)
alias table_at element_at # Backwards compatibility with Cucumber
end
- module Methods
+ module Methods #:nodoc:
delegate_to_session :element_at, :table_at
end
- class Session
+ class Session #:nodoc:
def_delegators :current_scope, :element_at, :table_at
end
end
8 lib/cucumber/world.rb
View
@@ -1,5 +1,5 @@
module Cucumber
- # All steps are run in the context of an object that extends this module
+ # All steps are run in the context of an object that extends this module.
module World
class << self
def alias_adverb(adverb)
@@ -9,7 +9,8 @@ def alias_adverb(adverb)
attr_writer :__cucumber_step_mother
- # Call a step from within a step definition
+ # Call a step from within a step definition. This method is aliased to
+ # the same i18n as RbDsl.
def __cucumber_invoke(name, multiline_argument=nil) #:nodoc:
begin
step_match = @__cucumber_step_mother.step_match(name)
@@ -57,6 +58,7 @@ def announce(announcement)
@__cucumber_step_mother.announce(announcement)
end
+ # Mark the matched step as pending.
def pending(message = "TODO")
if block_given?
begin
@@ -82,7 +84,7 @@ def pending(message = "TODO")
# or frameworks (Rails), so to avoid long waiting times on
# such errors in World we define it to just return a simple String.
#
- def inspect
+ def inspect #:nodoc:
sprintf("#<%s:0x%x>", self.class, self.object_id)
end
end
27 spec/cucumber/ast/visitor_spec.rb
View
@@ -1,27 +0,0 @@
-require File.dirname(__FILE__) + '/../../spec_helper'
-require 'cucumber/step_mother'
-require 'cucumber/ast'
-
-module Cucumber
- module Ast
- describe Visitor do
-
- it "should support checking scenario name matches regexps" do
- visitor = Visitor.new(mock("step mother"))
- scenario = Scenario.new(background=nil,
- comment=Comment.new(""),
- tags=Tags.new(0, []),
- line=99,
- keyword="",
- name="test name",
- steps=[])
-
- visitor.options = {:name_regexps => [/name/]}
-
- visitor.matches_scenario_names?(scenario).should be_true
- end
-
- end
- end
-end
-
Please sign in to comment.
Something went wrong with that request. Please try again.