Allow tests to be skipped

Summary:
Allow tests to be skipped by calling assertSkipped().  It's not really
an assertion of anything tangible; more like "assert that we can't
really assert anything right now".

Test Plan: Added a new test to the PhutilUnitTestEngineTestCase.

Reviewers: epriestley

Reviewed By: epriestley

CC: aran, Koolvin

Differential Revision: https://secure.phabricator.com/D2312

src/__phutil_library_map__.php

@@ -82,6 +82,7 @@ phutil_register_library_map(array(
     'ArcanistPatchWorkflow' => 'workflow/patch',
     'ArcanistPhutilModuleLinter' => 'lint/linter/phutilmodule',
     'ArcanistPhutilTestCase' => 'unit/engine/phutil/testcase',
+    'ArcanistPhutilTestSkippedException' => 'unit/engine/phutil/testcase/exception',
     'ArcanistPhutilTestTerminatedException' => 'unit/engine/phutil/testcase/exception',
     'ArcanistPyFlakesLinter' => 'lint/linter/pyflakes',
     'ArcanistPyLintLinter' => 'lint/linter/pylint',

src/unit/engine/phutil/__tests__/PhutilUnitTestEngineTestCase.php

@@ -40,7 +40,7 @@ final class PhutilUnitTestEngineTestCase extends ArcanistPhutilTestCase {
 
     self::$allTestsCounter--;
 
-    $actual_test_count = 4;
+    $actual_test_count = 5;
 
     $this->assertEqual(
       $actual_test_count,
@@ -86,6 +86,10 @@ final class PhutilUnitTestEngineTestCase extends ArcanistPhutilTestCase {
     $this->assertFailure('This test is expected to fail.');
   }
 
+  public function testSkip() {
+    $this->assertSkipped('This test is expected to skip.');
+  }
+
   public function testTryTestCases() {
     $this->tryTestCases(
       array(

src/unit/engine/phutil/testcase/ArcanistPhutilTestCase.php

@@ -109,6 +109,19 @@ abstract class ArcanistPhutilTestCase {
     throw new ArcanistPhutilTestTerminatedException($message);
   }
 
+  /**
+   * End this test by asserting that the test should be skipped for some
+   * reason.
+   *
+   * @param   string  Reason for skipping this test.
+   * @return  void
+   * @task    assert
+   */
+  final protected function assertSkipped($message) {
+    $this->skipTest($message);
+    throw new ArcanistPhutilTestTerminatedException($message);
+  }
+
 
 /* -(  Exception Handling  )------------------------------------------------- */
 
@@ -367,6 +380,26 @@ abstract class ArcanistPhutilTestCase {
   }
 
 
+  /**
+   * Mark the current running test as skipped.
+   *
+   * @param string  Description for why this test was skipped.
+   * @return void
+   * @task internal
+   */
+  final private function skipTest($reason) {
+    $coverage = $this->endCoverage();
+
+    $result = new ArcanistUnitTestResult();
+    $result->setCoverage($coverage);
+    $result->setName($this->runningTest);
+    $result->setResult(ArcanistUnitTestResult::RESULT_SKIP);
+    $result->setDuration(microtime(true) - $this->testStartTime);
+    $result->setUserData($reason);
+    $this->results[] = $result;
+  }
+
+
   /**
    * Execute the tests in this test case. You should not call this directly;
    * use @{class:PhutilUnitTestEngine} to orchestrate test execution.
@@ -411,6 +444,8 @@ abstract class ArcanistPhutilTestCase {
           }
         } catch (ArcanistPhutilTestTerminatedException $ex) {
           // Continue with the next test.
+        } catch (ArcanistPhutilTestSkippedException $ex) {
+          // Continue with the next test.
         } catch (Exception $ex) {
           $ex_class = get_class($ex);
           $ex_message = $ex->getMessage();

src/unit/engine/phutil/testcase/exception/ArcanistPhutilTestSkippedException.php

@@ -0,0 +1,24 @@
+<?php
+
+/*
+ * Copyright 2012 Facebook, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/**
+ * Thrown to skip test execution.
+ *
+ * @group unitrun
+ */
+final class ArcanistPhutilTestSkippedException extends Exception {}

src/unit/engine/phutil/testcase/exception/__init__.php

@@ -7,4 +7,5 @@
 
 
 
+phutil_require_source('ArcanistPhutilTestSkippedException.php');
 phutil_require_source('ArcanistPhutilTestTerminatedException.php');