ScalaTest 1.0
org.scalatest.junit

class JUnit3Suite
[source: org/scalatest/junit/JUnit3Suite.scala]
class JUnit3Suite
extends junit.framework.TestCase with Suite with AssertionsForJUnit
A Suite that is also a junit.framework.TestCase.

A JUnit3Suite may be run by either JUnit 3 (such as JUnit 3.8) or ScalaTest's runner. You write it the way you write a JUnit 3 TestCase. Tests are methods that start with test, take no parameters, and have a Unit return type. You manage fixtures with methods setUp and tearDown. Here's an example: 

 import org.scalatest.junit.JUnit3Suite
 import scala.collection.mutable.ListBuffer

 class BlastFromThePastSuite extends JUnit3Suite {

   var sb: StringBuilder = _
   var lb: ListBuffer[String] = _

   override def setUp() {
     sb = new StringBuilder("ScalaTest is ")
     lb = new ListBuffer[String]
   }

   def testEasy() { // Uses JUnit-style assertions
     sb.append("easy!")
     assertEquals("ScalaTest is easy!", sb.toString)
     assertTrue(lb.isEmpty)
     lb += "sweet"
   }

   def testFun() { // Uses ScalaTest assertions
     sb.append("fun!")
     assert(sb.toString === "ScalaTest is fun!")
     assert(lb.isEmpty)
   }
 }

You can use either JUnit's assertions, inherited from TestCase, or ScalaTest's, inherited from AssertionsForJUnit. You can also mix in ShouldMatchersForJUnit or MustMatchersForJUnit if you want to use ScalaTests's matchers DSL. Here's an example: 

 import org.scalatest.junit.JUnit3Suite
 import org.scalatest.junit.MustMatchersForJUnit
 import scala.collection.mutable.ListBuffer

 class BlastFromThePastSuite extends JUnit3Suite with MustMatchersForJUnit {

   var stringBuilder: StringBuilder = _
   var listBuffer: ListBuffer[String] = _

   override def setUp() {
     stringBuilder = new StringBuilder("ScalaTest is ")
     listBuffer = new ListBuffer[String]
   }

   def testEasy() {
     stringBuilder.append("easy!")
     stringBuilder.toString must be ("ScalaTest is easy!")
     listBuffer must be ('empty)
     listBuffer += "sweet"
   }

   def testFun() {
     stringBuilder.append("fun!")
     stringBuilder.toString must be ("ScalaTest is fun!")
     listBuffer must be ('empty)
   }
 }

The reason you would ordinarily want to mix in MustMatchersForJUnit or ShouldMatchersForJUnit rather than MustMatchers or ShouldMatchers is that MustMatchersForJUnit and ShouldMatchersForJUnit throw junit.framework.AssertionFailedErrors, which JUnit 3 will report as failures, not errors.

When writing JUnit 3 tests in Scala, you should keep in mind that JUnit 3 will not run tests that have a return type other than Unit. Thus it is best to leave off the equals sign before the curly braces of the body of the test, like this: 

 def testGoodIdea() { // result type will be Unit
   // ...
 }

Instead of this: 

 def testBadIdea() = { // result type will be inferred
   // ...
 }

If the testBadIdea method ends in an expression that has a result type other than Unit, the Scala compiler will infer a result type to the testBadIdea method to be the same non-Unit type. As a "result," JUnit 3 will not discover or run the testBadIdea method at all.

Author
Bill Venners
Method Summary
override def expectedTestCount (filter : Filter) : Int
Returns the number of tests expected to be run by JUnit when run is invoked on this Suite.
override def run (testName : scala.Option[java.lang.String], reporter : Reporter, stopper : Stopper, filter : Filter, configMap : scala.collection.immutable.Map[java.lang.String, Any], distributor : scala.Option[Distributor], tracker : Tracker) : Unit
Runs this suite of tests.
protected override final def runNestedSuites (reporter : Reporter, stopper : Stopper, filter : Filter, configMap : scala.collection.immutable.Map[java.lang.String, Any], distributor : scala.Option[Distributor], tracker : Tracker) : Unit
Throws UnsupportedOperationException, because this method is unused by this class, given this class's run method delegates to JUnit to run its tests.
protected override final def runTest (testName : java.lang.String, reporter : Reporter, stopper : Stopper, configMap : scala.collection.immutable.Map[java.lang.String, Any], tracker : Tracker) : Unit
Throws UnsupportedOperationException, because this method is unused by this class, given this class's run method delegates to JUnit to run its tests.
protected override final def runTests (testName : scala.Option[java.lang.String], reporter : Reporter, stopper : Stopper, filter : Filter, configMap : scala.collection.immutable.Map[java.lang.String, Any], distributor : scala.Option[Distributor], tracker : Tracker) : Unit
Throws UnsupportedOperationException, because this method is unused by this class, given this class's run method delegates to JUnit to run its tests.
override def tags : scala.collection.immutable.Map[java.lang.String, Nothing]
Returns an empty Map, because tags are not supported by JUnit 3.
override def testNames : scala.collection.immutable.Set[java.lang.String]
Returns the set of test names that will be executed by JUnit when run is invoked on an instance of this class, or the instance is passed directly to JUnit for running.
protected override final def withFixture (test : NoArgTest) : Unit
Throws UnsupportedOperationException, because this method is unused by this class, given this class's run method delegates to JUnit to run its tests.
Methods inherited from Suite
nestedSuites, execute, execute, execute, execute, groups, suiteName, pending, pendingUntilFixed
Methods inherited from Assertions
assert, assert, assert, assert, convertToEqualizer, intercept, expect, expect, fail, fail, fail, fail
Methods inherited from junit.framework.TestCase
junit.framework.TestCase.countTestCases, junit.framework.TestCase.createResult, junit.framework.TestCase.run, junit.framework.TestCase.run, junit.framework.TestCase.runBare, junit.framework.TestCase.runTest, junit.framework.TestCase.setUp, junit.framework.TestCase.tearDown, junit.framework.TestCase.toString, junit.framework.TestCase.getName, junit.framework.TestCase.setName
Methods inherited from AnyRef
getClass, hashCode, equals, clone, notify, notifyAll, wait, wait, wait, finalize, ==, !=, eq, ne, synchronized
Methods inherited from Any
==, !=, isInstanceOf, asInstanceOf
Method Details
override def testNames : scala.collection.immutable.Set[java.lang.String]
Returns the set of test names that will be executed by JUnit when run is invoked on an instance of this class, or the instance is passed directly to JUnit for running.

The iterator obtained by invoking elements on this returned Set will produce the test names in their natural order, as determined by String's compareTo method. Nevertheless, this method is not consulted by JUnit when it runs the tests, and JUnit may run the tests in any order.

Overrides
Suite.testNames
override def tags : scala.collection.immutable.Map[java.lang.String, Nothing]
Returns an empty Map, because tags are not supported by JUnit 3.
Overrides
Suite.tags
override def expectedTestCount(filter : Filter) : Int
Returns the number of tests expected to be run by JUnit when run is invoked on this Suite.

If tagsToInclude in the passed Filter is defined, this class's implementation of this method returns 0. Else this class's implementation of this method returns the size of the set returned by testNames on the current instance.

Overrides
Suite.expectedTestCount
protected override final def withFixture(test : NoArgTest) : Unit
Throws UnsupportedOperationException, because this method is unused by this class, given this class's run method delegates to JUnit to run its tests.

The main purpose of this method implementation is to render a compiler error an attempt to mix in a trait that overrides withFixture. Because this trait does not actually use withFixture, the attempt to mix in behavior would very likely not work.

Parameters
test - the no-arg test function to run with a fixture
Overrides
Suite.withFixture
protected override final def runNestedSuites(reporter : Reporter, stopper : Stopper, filter : Filter, configMap : scala.collection.immutable.Map[java.lang.String, Any], distributor : scala.Option[Distributor], tracker : Tracker) : Unit
Throws UnsupportedOperationException, because this method is unused by this class, given this class's run method delegates to JUnit to run its tests.

The main purpose of this method implementation is to render a compiler error an attempt to mix in a trait that overrides runNestedSuites. Because this trait does not actually use runNestedSuites, the attempt to mix in behavior would very likely not work.

Parameters
reporter - the Reporter to which results will be reported
stopper - the Stopper that will be consulted to determine whether to stop execution early.
filter - a Filter with which to filter tests based on their tags
configMap - a Map of key-value pairs that can be used by the executing Suite of tests.
distributor - an optional Distributor, into which to put nested Suites to be run by another entity, such as concurrently by a pool of threads. If None, nested Suites will be run sequentially.
tracker - a Tracker tracking Ordinals being fired by the current thread.
Throws
UnsupportedOperationException - always.
Overrides
Suite.runNestedSuites
protected override final def runTests(testName : scala.Option[java.lang.String], reporter : Reporter, stopper : Stopper, filter : Filter, configMap : scala.collection.immutable.Map[java.lang.String, Any], distributor : scala.Option[Distributor], tracker : Tracker) : Unit
Throws UnsupportedOperationException, because this method is unused by this class, given this class's run method delegates to JUnit to run its tests.

The main purpose of this method implementation is to render a compiler error an attempt to mix in a trait that overrides runTests. Because this trait does not actually use runTests, the attempt to mix in behavior would very likely not work.

Parameters
testName - an optional name of one test to run. If None, all relevant tests should be run. I.e., None acts like a wildcard that means run all relevant tests in this Suite.
reporter - the Reporter to which results will be reported
stopper - the Stopper that will be consulted to determine whether to stop execution early.
filter - a Filter with which to filter tests based on their tags
configMap - a Map of key-value pairs that can be used by the executing Suite of tests.
distributor - an optional Distributor, into which to put nested Suites to be run by another entity, such as concurrently by a pool of threads. If None, nested Suites will be run sequentially.
tracker - a Tracker tracking Ordinals being fired by the current thread.
Throws
UnsupportedOperationException - always.
Overrides
Suite.runTests
protected override final def runTest(testName : java.lang.String, reporter : Reporter, stopper : Stopper, configMap : scala.collection.immutable.Map[java.lang.String, Any], tracker : Tracker) : Unit
Throws UnsupportedOperationException, because this method is unused by this class, given this class's run method delegates to JUnit to run its tests.

The main purpose of this method implementation is to render a compiler error an attempt to mix in a trait that overrides runTest. Because this trait does not actually use runTest, the attempt to mix in behavior would very likely not work.

Parameters
testName - the name of one test to run.
reporter - the Reporter to which results will be reported
stopper - the Stopper that will be consulted to determine whether to stop execution early.
configMap - a Map of key-value pairs that can be used by the executing Suite of tests.
tracker - a Tracker tracking Ordinals being fired by the current thread.
Throws
UnsupportedOperationException - always.
Overrides
Suite.runTest
override def run(testName : scala.Option[java.lang.String], reporter : Reporter, stopper : Stopper, filter : Filter, configMap : scala.collection.immutable.Map[java.lang.String, Any], distributor : scala.Option[Distributor], tracker : Tracker) : Unit
Runs this suite of tests.

If testName is None, this trait's implementation of this method calls these two methods on this object in this order:

  1. runNestedSuites(report, stopper, tagsToInclude, tagsToExclude, configMap, distributor)
  2. runTests(testName, report, stopper, tagsToInclude, tagsToExclude, configMap)

If testName is defined, then this trait's implementation of this method calls runTests, but does not call runNestedSuites. This behavior is part of the contract of this method. Subclasses that override run must take care not to call runNestedSuites if testName is defined. (The OneInstancePerTest trait depends on this behavior, for example.)

Subclasses and subtraits that override this run method can implement them without invoking either the runTests or runNestedSuites methods, which are invoked by this trait's implementation of this method. It is recommended, but not required, that subclasses and subtraits that override run in a way that does not invoke runNestedSuites also override runNestedSuites and make it final. Similarly it is recommended, but not required, that subclasses and subtraits that override run in a way that does not invoke runTests also override runTests (and runTest, which this trait's implementation of runTests calls) and make it final. The implementation of these final methods can either invoke the superclass implementation of the method, or throw an UnsupportedOperationException if appropriate. The reason for this recommendation is that ScalaTest includes several traits that override these methods to allow behavior to be mixed into a Suite. For example, trait BeforeAndAfterEach overrides runTestss. In a Suite subclass that no longer invokes runTests from run, the BeforeAndAfterEach trait is not applicable. Mixing it in would have no effect. By making runTests final in such a Suite subtrait, you make the attempt to mix BeforeAndAfterEach into a subclass of your subtrait a compiler error. (It would fail to compile with a complaint that BeforeAndAfterEach is trying to override runTests, which is a final method in your trait.)

Parameters
testName - an optional name of one test to run. If None, all relevant tests should be run. I.e., None acts like a wildcard that means run all relevant tests in this Suite.
reporter - the Reporter to which results will be reported
stopper - the Stopper that will be consulted to determine whether to stop execution early.
filter - a Filter with which to filter tests based on their tags
configMap - a Map of key-value pairs that can be used by the executing Suite of tests.
distributor - an optional Distributor, into which to put nested Suites to be run by another entity, such as concurrently by a pool of threads. If None, nested Suites will be run sequentially.
tracker - a Tracker tracking Ordinals being fired by the current thread.
Throws
NullPointerException - if any passed parameter is null.
IllegalArgumentException - if testName is defined, but no test with the specified test name exists in this Suite
Overrides
Suite.run
Copyright (C) 2001-2009 Artima, Inc. All rights reserved.
ScalaTest 1.0