From b85347c28c7709cba9db75bf04a632cfa61ec10f Mon Sep 17 00:00:00 2001 From: Jesse Luehrs Date: Tue, 5 Mar 2013 16:53:51 -0600 Subject: update docs --- index/index-n.html | 2 +- org/perl8/test/TestMore.html | 307 +++++++++++++++++++++++++++++++++++++------ org/perl8/test/package.html | 4 +- 3 files changed, 268 insertions(+), 45 deletions(-) diff --git a/index/index-n.html b/index/index-n.html index 8731b88..a646c68 100644 --- a/index/index-n.html +++ b/index/index-n.html @@ -22,7 +22,7 @@
test
note
-
TestBuilder
+
TestBuilder TestMore
number
TestResult
diff --git a/org/perl8/test/TestMore.html b/org/perl8/test/TestMore.html index 2451df0..c94202e 100644 --- a/org/perl8/test/TestMore.html +++ b/org/perl8/test/TestMore.html @@ -44,7 +44,108 @@ -
+

This class is an implementation of the excellent +Test::More testing library for +Perl. It provides a simple assertion-based testing API, which produces +TAP, which can be +parsed by any TAP consumer. This library includes several TAP-consuming +harnesses to use with tests using this class, including one that supports +testing via sbt test.

Basics

The most basic test looks like this:

+class MyTest extends TestMore {
+  ok(true)
+}
+

This runs a test containing a single assertion. This will generate a TAP +stream that looks like this:

+ok 1
+1..1
+

which can be parsed by one of the test harnesses provided by this library.

Running tests

The simplest way to run tests is through sbt. You can register this +framework with sbt by adding this line to your build.sbt file:

+testFrameworks += new TestFramework("org.perl8.test.sbt.Framework")
+

Then, any classes in your test directory which extend TestMore will be +automatically detected and run.

Assertions

This class contains many more assertion methods than just ok. Here is a +more extensive example (borrowed from Test::More's documentation):

+class MyTest extends TestMore {
+  ok(got == expected, testName)
+
+  is(got, expected, testName)
+  isnt(got, expected, testName)
+
+  diag("here's what went wrong")
+
+  like(got, """expected""".r, testName)
+  unlike(got, """expected""".r, testName)
+
+  skip(howMany, why) {
+    ok(foo(), testName)
+    is(foo(42), 23, testName)
+  }
+
+  todo(why) {
+    ok(foo(), testName)
+    is(foo(42), 23, testName)
+  }
+
+  pass(testName)
+  fail(testName)
+
+  BAIL_OUT(why)
+}
+

The difference between the simple ok method and the more specific +methods like is and like is in how failures are reported. If you write +this:

+ok(1 == 2)
+

the output will look like this:

+not ok 1
+#   Failed test at MyTest.scala line 4.
+

On the other hand, a more specific assertion such as:

+is(1, 2)
+

will produce more useful output:

+not ok 1
+#   Failed test at MyTest.scala line 4.
+#          got: 1
+#     expected: 2
+

In addition to assertions, there are also several methods which take a +block of code to run, to modify the assertions contained in that block.

The todo method runs tests which are expected to fail. If they do fail, +the failure is reported to the test harness as a normal succeeding test, +and nothing happens. If they succeed, they are still reported as a +succeeding test, but a message is displayed to the user indicating that +the todo indication can be removed.

The skip method takes a block which should not be run at all. This is +similar to todo, except that it is useful for tests which could cause +problems if they were to actually run. Since the tests are never run, it's +not possible to count how many tests there should be, so this must be +specified as a parameter.

The subtest method runs a block of assertions as though they were an +entirely separate test, and then reports the result of that test as a +single assertion in the test that called subtest.

Test plans

Normally, you can run any number of assertions within your class body, and +the framework will assume that if no exceptions were thrown, all of the +assertions that were meant to be run were actually run. Sometimes, +however, that may not be a safe assumption, especially with heavily +callback-driven code. In this case, you can specify exactly how many tests +you intend to run, and the number of tests actually run will be checked +against this at the end. To declare this, give a number to the TestMore +constructor:

+class MyTest extends TestMore(5) {
+  ???
+}
+

In addition, if the entire test should be skipped, you can give a plan of +SkipAll():

+class MyTest extends TestMore(SkipAll()) {
+  ???
+}
+

Extensions

These assertion methods are written with the intention of being +composable. You can write your own test methods which call is or ok on +more specific bits of data. The one issue here is that, as shown above, +test failure messages refer to the file and line where the is or ok +call was made. If you want this to instead point at the line where your +assertion helper method was called, you can use the hideTestMethod +method like this:

+trait MyTestHelpers { this: TestMore =>
+  def notok (cond: Boolean) = hideTestMethod {
+    ok(!cond)
+  }
+}
+

This way, the test failure will be reported from the line where notok +was called, not from the call to ok in the notok method. +

Linear Supertypes
DelayedInit, Test, AnyRef, Any
@@ -171,7 +272,7 @@
Definition Classes
Any
-
  • +

  • @@ -183,7 +284,11 @@ BAIL_OUT(desc: String): Unit

    - +

    Halt execution of the entire test suite.

    Halt execution of the entire test suite. +

    Example: +

    1. BAIL_OUT("can't connect to the database!") +

    +
  • @@ -226,7 +331,7 @@
    Definition Classes
    TestMore → DelayedInit
    -
  • +

  • @@ -238,7 +343,12 @@ diag(message: String): Unit

    - +

    Output a comment to Console.err.

    Output a comment to Console.err. This is intended to be visible to +users even when running the test under a summarizing harness. +

    Example: +

    1. diag("Testing with Scala " + util.Properties.versionString) +

    +
  • @@ -265,7 +375,7 @@
    Definition Classes
    AnyRef → Any
    -
  • +

  • @@ -277,8 +387,12 @@ fail(desc: String): Boolean

    - -
  • +

    An assertion that always fails, with a reason.

    An assertion that always fails, with a reason. +

    Example: +

    1. fail("we should never get here") +

    +
    +

  • @@ -290,7 +404,11 @@ fail: Boolean

    - +

    An assertion that always fails.

    An assertion that always fails. +

    Example: +

    1. fail() +

    +
  • @@ -333,7 +451,7 @@
    Definition Classes
    AnyRef → Any
    -
  • +

  • @@ -345,7 +463,18 @@ hideTestMethod[T](body: ⇒ T): T

    - +

    A helper method which should be used to wrap test utility methods.

    A helper method which should be used to wrap test utility methods. +Normally, when tests fail, a message is printed giving the file and line +number of the call to the test method. If you write your own test +methods, they will typically use the existing methods to generate +assertions, and so the file and line numbers will likely be much less +useful. Wrapping the body of your method in this method will ensure that +the file and line number that is reported is the line where your helper +method is called instead. +

    Example: +

    1. def testFixtures = hideTestMethod { ??? } +

    +
  • @@ -359,7 +488,7 @@
    Attributes
    protected
    -
  • +

  • @@ -371,8 +500,14 @@ is[T](got: T, expected: T, desc: String): Boolean

    - -
  • +

    Assert that two objects are equal (using ==), and describe the +assertion.

    Assert that two objects are equal (using ==), and describe the +assertion. +

    Example: +

    1. is(response.status, 200, "we got a 200 OK response") +

    +
    +

  • @@ -384,7 +519,11 @@ is[T](got: T, expected: T): Boolean

    - +

    Assert that two objects are equal (using ==).

    Assert that two objects are equal (using ==). +

    Example: +

    1. is(response.status, 200) +

    +
  • @@ -398,7 +537,7 @@
    Definition Classes
    Any
    -
  • +

  • @@ -410,8 +549,14 @@ isnt[T](got: T, expected: T, desc: String): Boolean

    - -
  • +

    Assert that two objects are not equal (using !=), and describe the +assertion.

    Assert that two objects are not equal (using !=), and describe the +assertion. +

    Example: +

    1. isnt(response.body, "", "we got a response body") +

    +
    +

  • @@ -423,8 +568,12 @@ isnt[T](got: T, expected: T): Boolean

    - -
  • +

    Assert that two objects are not equal (using !=).

    Assert that two objects are not equal (using !=). +

    Example: +

    1. isnt(response.body, "") +

    +
    +

  • @@ -436,8 +585,14 @@ like(got: String, rx: Regex, desc: String): Boolean

    - -
  • +

    Assert that a string matches a regular expression, and describe the +assertion.

    Assert that a string matches a regular expression, and describe the +assertion. +

    Example: +

    1. like(response.header("Content-Type"), """text/x?html""".r, "we got an html content type") +

    +
    +

  • @@ -449,7 +604,11 @@ like(got: String, rx: Regex): Boolean

    - +

    Assert that a string matches a regular expression.

    Assert that a string matches a regular expression. +

    Example: +

    1. like(response.header("Content-Type"), """text/x?html""".r) +

    +
  • @@ -463,6 +622,24 @@
    Definition Classes
    AnyRef
    +
  • + + +

    + + + def + + + note(message: String): Unit + +

    +

    Output a comment to Console.out.

    Output a comment to Console.out. This is intended to only be visible +when viewing the raw TAP stream. +

    Example: +

    1. note("Starting the response tests") +

    +
  • @@ -489,7 +666,7 @@
    Definition Classes
    AnyRef
    -
  • +

  • @@ -501,8 +678,12 @@ ok(cond: Boolean, desc: String): Boolean

    - -
  • +

    Assert that a condition is true, and describe the assertion.

    Assert that a condition is true, and describe the assertion. +

    Example: +

    1. ok(response.isSuccess, "the response succeeded") +

    +
    +

  • @@ -514,8 +695,12 @@ ok(cond: Boolean): Boolean

    - -
  • +

    Assert that a condition is true.

    Assert that a condition is true. +

    Example: +

    1. ok(response.isSuccess) +

    +
    +

  • @@ -527,8 +712,12 @@ pass(desc: String): Boolean

    - -
  • +

    An assertion that always succeeds, with a reason.

    An assertion that always succeeds, with a reason. +

    Example: +

    1. pass("this line of code should be executed") +

    +
    +

  • @@ -540,7 +729,11 @@ pass: Boolean

    - +

    An assertion that always succeeds.

    An assertion that always succeeds. +

    Example: +

    1. pass() +

    +
  • @@ -581,7 +774,7 @@ Console.err, so you can swap these out as required in order to parse it. stderr, where they are typically displayed as-is) prefix the message with a newline, to ensure that the output starts on its own line.

    • Definition Classes
    Test
    -
  • +

  • @@ -593,8 +786,8 @@ Console.err, so you can swap these out as required in order to parse it. runTests(terminalInUse: Boolean): Int

    -
    Definition Classes
    TestMore → Test
    -
  • +
    Attributes
    protected
    Definition Classes
    TestMore → Test
    +

  • @@ -606,8 +799,13 @@ Console.err, so you can swap these out as required in order to parse it. skip(count: Int, reason: String)(body: ⇒ Unit): Unit

    - -
  • +

    Mark a block of tests that should not be run at all.

    Mark a block of tests that should not be run at all. They are treated as +always passing. +

    Example: +

    1. skip(3, "too dangerous to run for now") { ??? } +

    +
    +

  • @@ -619,7 +817,16 @@ Console.err, so you can swap these out as required in order to parse it. subtest(name: String, plan: Plan = NoPlan)(body: ⇒ Unit): Boolean

    - +

    Declare a logical group of assertions, to be run as a single test.

    Declare a logical group of assertions, to be run as a single test. This +is effectively an entirely separate test, which is run, and the result +of that test is reported as a single assertion in the test that contains +it. The subtest can specify its own plan in the same way that the +overall test is allowed to. The name will be used as the description for +the single assertion that the overall test sees. +

    Example: +

    1. subtest("response tests") { ??? } +

    +
  • @@ -646,7 +853,7 @@ Console.err, so you can swap these out as required in order to parse it.
    Definition Classes
    AnyRef → Any
    -
  • +

  • @@ -658,8 +865,14 @@ Console.err, so you can swap these out as required in order to parse it. todo(reason: String)(body: ⇒ Unit): Unit

    - -
  • +

    Mark a block of tests as expected to fail.

    Mark a block of tests as expected to fail. If the tests which run in the +todo block fail, they will not be treated as test failures, and if they +succeed, the user will be notified. +

    Example: +

    1. todo("waiting on fixes elsewhere") { ??? } +

    +
    +

  • @@ -671,8 +884,12 @@ Console.err, so you can swap these out as required in order to parse it. unlike(got: String, rx: Regex, desc: String): Boolean

    - -
  • +

    Assert that a string doesn't match a regular expression.

    Assert that a string doesn't match a regular expression. +

    Example: +

    1. unlike(response.header("Authorization"), """^Digest.*""".r, "we don't support digest authentication") +

    +
    +

  • @@ -684,7 +901,11 @@ Console.err, so you can swap these out as required in order to parse it. unlike(got: String, rx: Regex): Boolean

    - +

    Assert that a string doesn't match a regular expression.

    Assert that a string doesn't match a regular expression. +

    Example: +

    1. unlike(response.header("Authorization"), """^Digest.*""".r) +

    +
  • diff --git a/org/perl8/test/package.html b/org/perl8/test/package.html index eaf77f2..f3276f2 100644 --- a/org/perl8/test/package.html +++ b/org/perl8/test/package.html @@ -176,7 +176,9 @@ TestMore extends Test with DelayedInit - +

    This class is an implementation of the excellent +Test::More testing library for +Perl.

    • -- cgit v1.2.3-54-g00ecf