Module: Dfect

Included in:

Object

Defined in:

lib/dfect.rb,
lib/dfect/mini.rb,
lib/dfect/spec.rb,
lib/dfect/unit.rb,
lib/dfect/inochi.rb

Constant Summary

D =

Allows before and after hooks to be specified via the following method syntax when this module is mixed-in:

  D .<< { puts "before all nested tests" }
  D .<  { puts "before each nested test" }
  D .>  { puts "after  each nested test" }
  D .>> { puts "after  all nested tests" }

self

PROJECT =

Official name of this project.

"Dfect"

TAGLINE =

Short single-line description of this project.

"Assertion testing library for Ruby"

WEBSITE =

Address of this project’s official home page.

"http://snk.tuxfamily.org/lib/dfect/"

VERSION =

Number of this release of this project.

"2.1.0"

RELDATE =

Date of this release of this project.

"2010-03-31"

INSTDIR =

Location of this release of this project.

File.expand_path('../../..', __FILE__)

RUNTIME =

RubyGems required by this project during runtime.

Examples:

RUNTIME = {
  # this project needs exactly version 1.2.3 of the "an_example" gem
  "an_example" => [ "1.2.3" ],

  # this project needs at least version 1.2 (but not
  # version 1.2.4 or newer) of the "another_example" gem
  "another_example" => [ ">= 1.2" , "< 1.2.4" ],

  # this project needs any version of the "yet_another_example" gem
  "yet_another_example" => [],
}

{}

DEVTIME =

RubyGems required by this project during development.

Examples:

DEVTIME = {
  # this project needs exactly version 1.2.3 of the "an_example" gem
  "an_example" => [ "1.2.3" ],

  # this project needs at least version 1.2 (but not
  # version 1.2.4 or newer) of the "another_example" gem
  "another_example" => [ ">= 1.2" , "< 1.2.4" ],

  # this project needs any version of the "yet_another_example" gem
  "yet_another_example" => [],
}

{
  "inochi" => [ "~> 2" ], # for managing this project
}

Class Attribute Summary

• + (Object) options

  Hash of choices that affect how Dfect operates.

• + (Object) report readonly

  Hash of test results, assembled by Dfect.run.

Class Method Summary

• + (Object) <(&block)

  Registers the given block to be executed before each nested test inside this test.

• + (Object) <<(&block)

  Registers the given block to be executed before all nested tests inside this test.

• + (Object) >(&block)

  Registers the given block to be executed after each nested test inside this test.

• + (Object) >>(&block)

  Registers the given block to be executed after all nested tests inside this test.

• + (Object) C(symbol, message = nil, &block)

  Asserts that the given symbol is thrown when the given block is executed.

• + (Object) C!(symbol, message = nil, &block)

  Asserts that the given symbol is not thrown when the given block is executed.

• + (Boolean) C?(symbol, message = nil, &block)

  Returns true if the given symbol is thrown when the given block is executed.

• + (Object) D(*description, &block)

  Defines a new test composed of the given description and the given block to execute.

• + (Object) D!(*description, &block)

  Defines a new test that is explicitly insulated from the tests that contain it and also from the top-level Ruby environment.

• + (Object) E(*kinds_then_message, &block)

  Asserts that one of the given kinds of exceptions is raised when the given block is executed.

• + (Object) E!(*kinds_then_message, &block)

  Asserts that one of the given kinds of exceptions is not raised when the given block is executed.

• + (Boolean) E?(*kinds_then_message, &block)

  Returns true if one of the given kinds of exceptions is raised when the given block is executed.

• + (Boolean) F?(message = nil, &block)

  Returns true if the result of the given block is either nil or false.

• + (Object) info

  Returns the details of the failure that is currently being debugged by the user.

• + (Object) inspect

  Description of this release of this project.

• + (Object) L(*messages)

  Adds the given messages to the report inside the section of the currently running test.

• + (Object) require(gem_name_or_library)

  Loads the correct version (as defined by the RUNTIME or DEVTIME constant in this module) of the given gem or the gem that contains the given library.

• + (Object) run(continue = true)

  Executes all tests defined thus far and stores the results in Dfect.report.

• + (Object) S(identifier, &block)

  Mechanism for sharing code between tests.

• + (Object) S!(identifier, &block)

  Shares the given code block under the given identifier and then immediately injects that code block into the closest insulated Dfect test that contains the call to this method.

• + (Boolean) S?(identifier)

  Checks whether any code has been shared under the given identifier.

• + (Object) stop

  Stops the execution of the Dfect.run method or raises an exception if that method is not currently executing.

• + (Object) T(condition = nil, message = nil, &block) (also: F!)

  Asserts that the given condition or the result of the given block is neither nil nor false and returns that result.

• + (Object) T!(condition = nil, message = nil, &block) (also: F)

  Asserts that the given condition or the result of the given block is either nil or false and returns that result.

• + (Boolean) T?(condition = nil, message = nil, &block)

  Returns true if the given condition or the result of the given block is neither nil nor false.

Instance Method Summary

• - (Object) after(what, &block)
• - (Object) before(what, &block)

88
89
90

# File 'lib/dfect.rb', line 88

def options
  @options
end

70
71
72

# File 'lib/dfect.rb', line 70

def report
  @report
end

D .< { puts "before each nested test" }

D .< do
  puts "before each nested test"
end

177
178
179
180
181
182
183
184
185

# File 'lib/dfect.rb', line 177

def <(*args, &block)
  if args.empty?
    raise ArgumentError, 'block must be given' unless block
    @suite.before_each << block
  else
    # the < method is being used as a check for inheritance
    super
  end
end

D .<< { puts "before all nested tests" }

D .<< do
  puts "before all nested tests"
end

216
217
218
219

# File 'lib/dfect.rb', line 216

def << &block
  raise ArgumentError, 'block must be given' unless block
  @suite.before_all << block
end

D .> { puts "after each nested test" }

D .> do
  puts "after each nested test"
end

199
200
201
202

# File 'lib/dfect.rb', line 199

def > &block
  raise ArgumentError, 'block must be given' unless block
  @suite.after_each << block
end

D .>> { puts "after all nested tests" }

D .>> do
  puts "after all nested tests"
end

233
234
235
236

# File 'lib/dfect.rb', line 233

def >> &block
  raise ArgumentError, 'block must be given' unless block
  @suite.after_all << block
end

C(:foo) { throw :foo, 123 } # passes, => 123
C(:foo) { throw :bar, 456 } # fails,  => 456
C(:foo) { }                 # fails,  => nil

C(:foo, ":foo must be thrown") { throw :bar, 789 } # fails, => nil

469
470
471

# File 'lib/dfect.rb', line 469

def C symbol, message = nil, &block
  assert_catch :assert, symbol, message, &block
end

C!(:foo) { throw :foo, 123 } # fails,  => nil
C!(:foo) { throw :bar, 456 } # passes, => nil
C!(:foo) { }                 # passes, => nil

C!(:foo, ":foo must be thrown") { throw :bar, 789 } # passes, => nil

495
496
497

# File 'lib/dfect.rb', line 495

def C! symbol, message = nil, &block
  assert_catch :negate, symbol, message, &block
end

C?(:foo) { throw :foo, 123 } # => true
C?(:foo) { throw :bar, 456 } # => false
C?(:foo) { }                 # => false

C?(:foo, ":foo must be thrown") { throw :bar, 789 } # => false

517
518
519

# File 'lib/dfect.rb', line 517

def C? symbol, message = nil, &block
  assert_catch :sample, symbol, message, &block
end

D "a new array" do
  D .< { @array = [] }

  D "must be empty" do
    T { @array.empty? }
  end

  D "when populated" do
    D .< { @array.push 55 }

    D "must not be empty" do
      F { @array.empty? }
    end
  end
end

122
123
124

# File 'lib/dfect.rb', line 122

def D *description, &block
  create_test @tests.empty?, *description, &block
end

D "a root-level test" do
  @outside = 1
  T { defined? @outside }
  T { @outside == 1 }

  D "an inner, non-insulated test" do
    T { defined? @outside }
    T { @outside == 1 }
  end

  D! "an inner, insulated test" do
    F { defined? @outside }
    F { @outside == 1 }

    @inside = 2
    T { defined? @inside }
    T { @inside == 2 }
  end

  F { defined? @inside }
  F { @inside == 2 }
end

159
160
161

# File 'lib/dfect.rb', line 159

def D! *description, &block
  create_test true, *description, &block
end

E { }       # fails
E { raise } # passes

E(ArgumentError) { raise ArgumentError }
E(ArgumentError, "argument must be invalid") { raise ArgumentError }

E(SyntaxError, NameError) { eval "..." }
E(SyntaxError, NameError, "string must compile") { eval "..." }

376
377
378

# File 'lib/dfect.rb', line 376

def E *kinds_then_message, &block
  assert_raise :assert, *kinds_then_message, &block
end

E! { }       # passes
E! { raise } # fails

E!(ArgumentError) { raise ArgumentError } # fails
E!(ArgumentError, "argument must be invalid") { raise ArgumentError }

E!(SyntaxError, NameError) { eval "..." }
E!(SyntaxError, NameError, "string must compile") { eval "..." }

403
404
405

# File 'lib/dfect.rb', line 403

def E! *kinds_then_message, &block
  assert_raise :negate, *kinds_then_message, &block
end

E? { }       # => false
E? { raise } # => true

E?(ArgumentError) { raise ArgumentError } # => true

E?(SyntaxError, NameError) { eval "..." } # => true
E!(SyntaxError, NameError, "string must compile") { eval "..." }

437
438
439

# File 'lib/dfect.rb', line 437

def E? *kinds_then_message, &block
  assert_raise :sample, *kinds_then_message, &block
end

F? { true }  # => false
F? { false } # => true
F? { nil }   # => true

F?( "computers do not doublethink" ) { 2 + 2 == 5 } # => true

335
336
337

# File 'lib/dfect.rb', line 335

def F? message = nil, &block
  not T? message, &block
end

675
676
677

# File 'lib/dfect.rb', line 675

def info
  @trace.last
end

31
32
33

# File 'lib/dfect/inochi.rb', line 31

def self.inspect
  "#{PROJECT} #{VERSION} (#{RELDATE})"
end

L "establishing connection..."

L "beginning calculation...", Math::PI, [1, 2, 3, ['a', 'b', 'c']]

539
540
541

# File 'lib/dfect.rb', line 539

def L *messages
  @trace.concat messages
end

85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100

# File 'lib/dfect/inochi.rb', line 85

def self.require gem_name_or_library
  # prepare the correct version of the gem for loading
  if respond_to? :gem
    gem_name = gem_name_or_library.to_s.sub(%r{/.*$}, '')
    if gem_version = RUNTIME[gem_name] || DEVTIME[gem_name]
      begin
        gem gem_name, *gem_version
      rescue LoadError => error
        warn "#{self.inspect}: #{error}"
      end
    end
  end

  # do the loading
  super
end

636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661

# File 'lib/dfect.rb', line 636

def run continue = true
  # clear previous results
  unless continue
    @stats.clear
    @trace.clear
    @tests.clear
  end

  # make new results
  start = Time.now
  catch(:stop_dfect_execution) { execute }
  finish = Time.now
  @stats[:time] = finish - start

  # print new results
  unless @stats.key? :fail or @stats.key? :error
    #
    # show execution trace only if all tests passed.
    # otherwise, we will be repeating already printed
    # failure details and obstructing the developer!
    #
    display @trace
  end

  display @stats
end

S :knowledge do
  #...
end

D "some test" do
  S :knowledge
end

D "another test" do
  S :knowledge
end

572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593

# File 'lib/dfect.rb', line 572

def S identifier, &block
  if block_given?
    if already_shared = @share[identifier]
      raise ArgumentError, "A code block #{already_shared.inspect} has already been shared under the identifier #{identifier.inspect}."
    end

    @share[identifier] = block

  elsif block = @share[identifier]
    if @tests.empty?
      raise "Cannot inject code block #{block.inspect} shared under identifier #{identifier.inspect} outside of a Dfect test."
    else
      # find the closest insulated parent test; this should always
      # succeed because root-level tests are insulated by default
      test = @tests.reverse.find {|t| t.sandbox }
      test.sandbox.instance_eval(&block)
    end

  else
    raise ArgumentError, "No code block is shared under identifier #{identifier.inspect}."
  end
end

D "some test" do
  S! :knowledge do
    #...
  end
end

D "another test" do
  S :knowledge
end

615
616
617
618
619

# File 'lib/dfect.rb', line 615

def S! identifier, &block
  raise 'block must be given' unless block_given?
  S identifier, &block
  S identifier
end

624
625
626

# File 'lib/dfect.rb', line 624

def S? identifier
  @share.key? identifier
end

667
668
669

# File 'lib/dfect.rb', line 667

def stop
  throw :stop_dfect_execution
end

T { true }  # passes
T { false } # fails
T { nil }   # fails

T("computers do not doublethink") { 2 + 2 != 5 } # passes

263
264
265

# File 'lib/dfect.rb', line 263

def T condition = nil, message = nil, &block
  assert_yield :assert, condition, message, &block
end

T! { true }  # fails
T! { false } # passes
T! { nil }   # passes

T!("computers do not doublethink") { 2 + 2 == 5 } # passes

286
287
288

# File 'lib/dfect.rb', line 286

def T! condition = nil, message = nil, &block
  assert_yield :negate, condition, message, &block
end

T? { true }  # => true
T? { false } # => false
T? { nil }   # => false

T?("computers do not doublethink") { 2 + 2 != 5 } # => true

311
312
313

# File 'lib/dfect.rb', line 311

def T? condition = nil, message = nil, &block
  assert_yield :sample, condition, message, &block
end

21
22
23
24
25
26
27
28
29
30

# File 'lib/dfect/spec.rb', line 21

def after what, &block
  meth =
    case what
    when :each then :>
    when :all  then :>>
    else raise ArgumentError, what
    end

  send meth, &block
end

10
11
12
13
14
15
16
17
18
19

# File 'lib/dfect/spec.rb', line 10

def before what, &block
  meth =
    case what
    when :each then :<
    when :all  then :<<
    else raise ArgumentError, what
    end

  send meth, &block
end