Merge branch 'release/v0.39'

Changes

@@ -1,5 +1,10 @@
 Revision history for Perl extension Test::Spec.
 
+0.38 Wed Aug 31 00:52:00 EST 2011
+  - Added xit/xthey/xdescribe to mark TODO tests, inspired by the
+    Jasmine JavaScript framework.
+    Contributed by Marian Schubert (issue #10).
+
 0.38 Sat Jul 09 23:16:00 EST 2011
   - Added share() function to facilitate spec refactoring.
 
@@ -39,8 +44,8 @@ Revision history for Perl extension Test::Spec.
     through a harness like prove(1).
 
 0.29  Thu May 19 18:49:00 2011
-	- Quell annoying Test::Deep::isa() warnings.
+        - Quell annoying Test::Deep::isa() warnings.
 
 0.28  Thu May 19 11:15:58 2011
-	- Extracted from ICA::Test::Spec
+        - Extracted from ICA::Test::Spec
 

MANIFEST

@@ -10,6 +10,8 @@ t/another_shared_examples_spec.pl
 t/auto_inherit.t
 t/data_sharing.t
 t/define.t
+t/disabled.t
+t/disabled_spec.pl
 t/dying_spec.pl
 t/empty.t
 t/helper_test.pl

lib/Test/Spec.pm

@@ -3,7 +3,7 @@ use strict;
 use warnings;
 use Test::Trap ();        # load as early as possible to override CORE::exit
 
-our $VERSION = '0.38';
+our $VERSION = '0.39';
 
 use base qw(Exporter);
 
@@ -17,8 +17,8 @@ use constant { DEFINITION_PHASE => 0, EXECUTION_PHASE => 1 };
 our $TODO;
 our $Debug = $ENV{TEST_SPEC_DEBUG} || 0;
 
-our @EXPORT      = qw(runtests describe before after it they *TODO
-                      share shared_examples_for it_should_behave_like
+our @EXPORT      = qw(runtests describe xdescribe before after it xit they
+                      xthey *TODO share shared_examples_for it_should_behave_like
                       spec_helper);
 our @EXPORT_OK   = ( @EXPORT, qw(DEFINITION_PHASE EXECUTION_PHASE $Debug) );
 our %EXPORT_TAGS = ( all => \@EXPORT_OK,
@@ -166,7 +166,11 @@ sub it(@) {
     Carp::croak "it() requires at least one of (description,code)";
   }
   $name ||= "behaves as expected (whatever that means)";
-  push @{ _autovivify_context($package)->tests }, { name => $name, code => $code };
+  push @{ _autovivify_context($package)->tests }, {
+    name => $name,
+    code => $code,
+    todo => $TODO,
+  };
   return;
 }
 
@@ -201,6 +205,22 @@ sub describe(@) {
   });
 }
 
+# used to easily disable suites/specs during development
+sub xit(@) {
+  local $TODO = '(disabled)';
+  it(@_);
+}
+
+sub xthey(@) {
+  local $TODO = '(disabled)';
+  they(@_);
+}
+
+sub xdescribe(@) {
+  local $TODO = '(disabled)';
+  describe(@_);
+}
+
 # shared_examples_for DESC => CODE
 sub shared_examples_for($&) {
   my $package = caller;
@@ -599,6 +619,12 @@ C<describe> blocks with the same name are allowed. They do not replace each
 other, rather subsequent C<describe>s extend the existing one of the same
 name.
 
+=item xdescribe
+
+Specification contexts may be disabled by calling C<xdescribe> instead of
+describe(). All examples inside an C<xdescribe> are reported as
+"# TODO (disabled)", which prevents Test::Harness/prove from counting them
+as failures.
 
 =item it SPECIFICATION => CODE
 
@@ -625,7 +651,7 @@ not failed.
 
 =item they CODE
 
-=item TODO_SPECIFICATION
+=item they TODO_SPECIFICATION
 
 An alias for L</it>.  This is useful for describing behavior for groups of
 items, so the verb agrees with the noun:
@@ -637,6 +663,12 @@ items, so the verb agrees with the noun:
     they "put the lotion in the basket"; # TODO
   };
 
+=item xit/xthey
+
+Examples may be disabled by calling xit()/xthey() instead of it()/they().
+These examples are reported as "# TODO (disabled)", which prevents
+Test::Harness/prove from counting them as failures.
+
 =item before each => CODE
 
 =item before all => CODE

lib/Test/Spec/Context.pm

@@ -288,7 +288,14 @@ sub _materialize_tests {
     # create a test subroutine in the correct package
     no strict 'refs';
     *{$fq_name} = sub {
-      if ($t->{code}) {
+      if (!$t->{code} || $t->{todo}) {
+        my $builder = $self->_builder;
+        local $TODO = $t->{todo} || "(unimplemented)";
+        $builder->todo_start($TODO);
+        $builder->ok(1, $description);
+        $builder->todo_end();
+      }
+      else {
         # copy these, because they'll be needed in a callback with its own @_
         my @test_args = @_;
 
@@ -374,13 +381,6 @@ sub _materialize_tests {
           die $secondary_err if $secondary_err;
         }
       }
-      else {
-        my $builder = $self->_builder;
-        local $TODO = "(unimplemented)";
-        $builder->todo_start($TODO);
-        $builder->ok(1, $description);
-        $builder->todo_end();
-      }
 
       $self->_debug(sub { print STDERR "\n" });
     };
@@ -466,7 +466,7 @@ sub contextualize {
   local $Test::Spec::_Current_Context = $self;
   local $self->{_has_run_on_enter} = {};
   local $self->{_has_run_on_leave} = {};
-  local $TODO;
+  local $TODO = $TODO;
   my @errs;
 
   eval { $self->_run_on_enter };
@@ -485,7 +485,7 @@ sub contextualize {
   if (@errs) {
     if ($TODO) {
       # make it easy for tests to declare todo status, just "$TODO++"
-      $TODO = "(unimplemented)" if $TODO eq '1';
+      $TODO = "(unimplemented)" if $TODO =~ /^\d+$/;
       # expected to fail
       Test::More::ok(1);
     }

t/disabled.t

@@ -0,0 +1,41 @@
+#!/usr/bin/env perl
+#
+# disabled.t
+#
+# Test cases for disabled specs (xit, xdescribe, xthey).
+# Executes disabled_spec.pl and validates its TAP output.
+#
+########################################################################
+#
+use strict;
+use warnings;
+use FindBin qw($Bin);
+BEGIN { require "$Bin/test_helper.pl" };
+
+use Test::More;
+use TAP::Parser;
+
+my @results = parse_tap("disabled_spec.pl");
+my %passing = map { $_->description => $_ } grep { $_->is_test } @results;
+
+sub test_passed {
+  my $desc = shift;
+  my $testdesc = "- $desc";
+  ok($passing{$testdesc}, $desc);
+}
+
+sub test_todo {
+  my $desc = shift;
+  my $testdesc = "- $desc";
+  ok($passing{$testdesc} && $passing{$testdesc}->directive eq 'TODO', $desc);
+}
+
+test_todo('Test::Spec disabled spec should not execute "it" examples');
+test_todo('Test::Spec disabled spec should not execute "they" examples');
+test_todo('Test::Spec should not execute disabled "it" example');
+test_todo('Test::Spec should not execute disabled "they" example');
+test_passed('Test::Spec should execute enabled "it" example');
+test_passed('Test::Spec should execute enabled "they" example');
+
+done_testing();
+

t/disabled_spec.pl

@@ -0,0 +1,39 @@
+#!/usr/bin/env perl
+#
+# disabled.t
+#
+# Disabled specs.
+#
+########################################################################
+#
+
+package Testcase::Spec::Disabled;
+use Test::Spec;
+
+describe 'Test::Spec' => sub {
+  xdescribe 'disabled spec' => sub {
+    it 'should not execute "it" examples' => sub {
+      fail;
+    };
+    they 'should not execute "they" examples' => sub {
+      fail;
+    };
+  };
+
+  xit 'should not execute disabled "it" example' => sub {
+    fail;
+  };
+
+  xthey 'should not execute disabled "they" example' => sub {
+    fail;
+  };
+
+  it 'should execute enabled "it" example' => sub {
+    pass;
+  };
+  they 'should execute enabled "they" example' => sub {
+    pass;
+  };
+};
+
+runtests unless caller;