TestMore

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("com.iinteractive.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

Instance Constructors

new TestMore(plan: Plan = test.this.`package`.NoPlan)

Value Members

final def !=(arg0: AnyRef): Boolean

Definition Classes
AnyRef
final def !=(arg0: Any): Boolean

Definition Classes
Any
final def ##(): Int

Definition Classes
AnyRef → Any
final def ==(arg0: AnyRef): Boolean

Definition Classes
AnyRef
final def ==(arg0: Any): Boolean

Definition Classes
Any
def 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!")
final def asInstanceOf[T0]: T0

Definition Classes
Any
def clone(): AnyRef

Attributes
protected[java.lang]
Definition Classes
AnyRef
Annotations
@throws()
def delayedInit(body: ⇒ Unit): Unit

Definition Classes
TestMore → DelayedInit
def diag(message: Any): 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)
def dies_ok[T <: Throwable](body: ⇒ Unit)(implicit arg0: ClassTag[T]): Boolean

Assert that the given block of code throws an exception.
Assert that the given block of code throws an exception.
Example:
1. dies_ok[MyException] { myObj.explode }
final def eq(arg0: AnyRef): Boolean

Definition Classes
AnyRef
def equals(arg0: Any): Boolean

Definition Classes
AnyRef → Any
def exception(body: ⇒ Unit): Option[Throwable]

Runs a block of code, returning the exception that it throws, or None if no exception was thrown.
Runs a block of code, returning the exception that it throws, or None if no exception was thrown. Not an assertion on its own, but can be used to create more complicated assertions about exceptions.
Example:
1. is(exception { myObj.explode }, None)
def 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")
def fail: Boolean

An assertion that always fails.
An assertion that always fails.
Example:
1. fail()
def finalize(): Unit

Attributes
protected[java.lang]
Definition Classes
AnyRef
Annotations
@throws()
final def getClass(): Class[_]

Definition Classes
AnyRef → Any
def hashCode(): Int

Definition Classes
AnyRef → Any
def 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 { ??? }
def ignoreFrame(frame: StackTraceElement): Boolean

Attributes
protected
def 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")
def 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)
final def isInstanceOf[T0]: Boolean

Definition Classes
Any
def 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")
def 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, "")
def 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")
def 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)
def lives_ok(body: ⇒ Unit): Boolean

Assert that the given block of code doesn't throw an exception.
Assert that the given block of code doesn't throw an exception.
Example:
1. lives_ok { myObj.explode }
final def ne(arg0: AnyRef): Boolean

Definition Classes
AnyRef
def note(message: Any): 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")
final def notify(): Unit

Definition Classes
AnyRef
final def notifyAll(): Unit

Definition Classes
AnyRef
def 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")
def ok(cond: Boolean): Boolean

Assert that a condition is true.
Assert that a condition is true.
Example:
1. ok(response.isSuccess)
def 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")
def pass: Boolean

An assertion that always succeeds.
An assertion that always succeeds.
Example:
1. pass()
def run: Int

Runs the test.
Runs the test. The TAP stream will be written to Console.out and Console.err, so you can swap these out as required in order to parse it.
returns
The exit code that the test produced. Success is indicated by 0, failure to run the correct number of tests by 255, and any other failure by the number of tests that failed. This should be used by reporters which run a single test, which can call sys.exit(exitCode)

Definition Classes
Test
def runInHarness: Int

Runs the test just like run, but in a way that makes sense when test results are being summarized rather than directly displayed.
Runs the test just like run, but in a way that makes sense when test results are being summarized rather than directly displayed.
Summarizing test reporters tend to repeatedly update the same line on the terminal, so this method makes calls to diag (which sends messages to 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
def runTests(terminalInUse: Boolean): Int

Attributes
protected
Definition Classes
TestMore → Test
def 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") { ??? }
def 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") { ??? }
final def synchronized[T0](arg0: ⇒ T0): T0

Definition Classes
AnyRef
def throws_ok(e: Throwable)(body: ⇒ Unit): Boolean

Assert that the given block of code throws an exception, and that the exception that it throws is equal to the passed exception.
Assert that the given block of code throws an exception, and that the exception that it throws is equal to the passed exception.
Example:
1. throws_ok(new MyException("foo")) { myObj.explode }
def toString(): String

Definition Classes
AnyRef → Any
def 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") { ??? }
def 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")
def 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)
final def wait(): Unit

Definition Classes
AnyRef
Annotations
@throws()
final def wait(arg0: Long, arg1: Int): Unit

Definition Classes
AnyRef
Annotations
@throws()
final def wait(arg0: Long): Unit

Definition Classes
AnyRef
Annotations
@throws()

class TestMore extends Test with DelayedInit

Basics

Running tests

Assertions

Test plans

Extensions

Instance Constructors

new TestMore(plan: Plan = test.this.`package`.NoPlan)

Value Members

final def !=(arg0: AnyRef): Boolean

final def !=(arg0: Any): Boolean

final def ##(): Int

final def ==(arg0: AnyRef): Boolean

final def ==(arg0: Any): Boolean

def BAIL_OUT(desc: String): Unit

final def asInstanceOf[T0]: T0

def clone(): AnyRef

def delayedInit(body: ⇒ Unit): Unit

def diag(message: Any): Unit

def dies_ok[T <: Throwable](body: ⇒ Unit)(implicit arg0: ClassTag[T]): Boolean

final def eq(arg0: AnyRef): Boolean

def equals(arg0: Any): Boolean

def exception(body: ⇒ Unit): Option[Throwable]

def fail(desc: String): Boolean

def fail: Boolean

def finalize(): Unit

final def getClass(): Class[_]

def hashCode(): Int

def hideTestMethod[T](body: ⇒ T): T

def ignoreFrame(frame: StackTraceElement): Boolean

def is[T](got: T, expected: T, desc: String): Boolean

def is[T](got: T, expected: T): Boolean

final def isInstanceOf[T0]: Boolean

def isnt[T](got: T, expected: T, desc: String): Boolean

def isnt[T](got: T, expected: T): Boolean

def like(got: String, rx: Regex, desc: String): Boolean

def like(got: String, rx: Regex): Boolean

def lives_ok(body: ⇒ Unit): Boolean

final def ne(arg0: AnyRef): Boolean

def note(message: Any): Unit

final def notify(): Unit

final def notifyAll(): Unit

def ok(cond: Boolean, desc: String): Boolean

def ok(cond: Boolean): Boolean

def pass(desc: String): Boolean

def pass: Boolean

def run: Int

def runInHarness: Int

def runTests(terminalInUse: Boolean): Int

def skip(count: Int, reason: String)(body: ⇒ Unit): Unit

def subtest(name: String, plan: Plan = NoPlan)(body: ⇒ Unit): Boolean

final def synchronized[T0](arg0: ⇒ T0): T0

def throws_ok(e: Throwable)(body: ⇒ Unit): Boolean

def toString(): String

def todo(reason: String)(body: ⇒ Unit): Unit

def unlike(got: String, rx: Regex, desc: String): Boolean

def unlike(got: String, rx: Regex): Boolean

final def wait(): Unit

final def wait(arg0: Long, arg1: Int): Unit

final def wait(arg0: Long): Unit

Inherited from DelayedInit

Inherited from Test

Inherited from AnyRef

Inherited from Any

Ungrouped