TestSuite

Class used via an implicit conversion to enable two objects to be compared with <code>===</code> and <code>!==</code> with a <code>Boolean</code> result and an enforced type constraint between two object types. For example:

<pre class="stHighlight"> assert(a === b) assert(c !== d) </pre>

You can also check numeric values against another with a tolerance. Here are some examples:

<pre class="stHighlight"> assert(a === (2.0 +- 0.1)) assert(c !== (2.0 +- 0.1)) </pre>

Class used via an implicit conversion to enable any two objects to be compared with <code>===</code> and <code>!==</code> with a <code>Boolean</code> result and no enforced type constraint between two object types. For example:

<pre class="stHighlight"> assert(a === b) assert(c !== d) </pre>

You can also check numeric values against another with a tolerance. Here are some examples:

<pre class="stHighlight"> assert(a === (2.0 +- 0.1)) assert(c !== (2.0 +- 0.1)) </pre>

A test function taking no arguments and returning a <code>FutureOutcome</code>.

For more detail and examples, see the relevant section in the <a href="AsyncFlatSpec.html#withFixtureNoArgTest">documentation for trait <code>AsyncFlatSpec</code></a>.

Class that provides the <code>lastly</code> method of the <code>complete</code>-<code>lastly</code> syntax.

Returns a <code>TripleEqualsInvocationOnSpread[T]</code>, given an <code>Spread[T]</code>, to facilitate the “<code><em><left></em> should !== (<em><pivot></em> +- <em><tolerance></em>)</code>” syntax of <a href="../scalatest/Matchers.html"><code>Matchers</code></a>.

Returns a <code>TripleEqualsInvocation[Null]</code>, given a <code>null</code> reference, to facilitate the “<code><em><left></em> should !== null</code>” syntax of <a href="../scalatest/Matchers.html"><code>Matchers</code></a>.

Returns a <code>TripleEqualsInvocation[T]</code>, given an object of type <code>T</code>, to facilitate the “<code><em><left></em> should !== <em><right></em></code>” syntax of <a href="../scalatest/Matchers.html"><code>Matchers</code></a>.

Returns a <code>TripleEqualsInvocationOnSpread[T]</code>, given an <code>Spread[T]</code>, to facilitate the “<code><em><left></em> should === (<em><pivot></em> +- <em><tolerance></em>)</code>” syntax of <a href="../scalatest/Matchers.html"><code>Matchers</code></a>.

Returns a <code>TripleEqualsInvocation[Null]</code>, given a <code>null</code> reference, to facilitate the “<code><em><left></em> should === null</code>” syntax of <a href="../scalatest/Matchers.html"><code>Matchers</code></a>.

Returns a <code>TripleEqualsInvocation[T]</code>, given an object of type <code>T</code>, to facilitate the “<code><em><left></em> should === <em><right></em></code>” syntax of <a href="../scalatest/Matchers.html"><code>Matchers</code></a>.

Returns an <code>Alerter</code> that during test execution will forward strings passed to its <code>apply</code> method to the current reporter. If invoked in a constructor, it will register the passed string for forwarding later during test execution. If invoked while this <code>AsyncFunSuite</code> is being executed, such as from inside a test function, it will forward the information to the current reporter immediately. If invoked at any other time, it will print to the standard output. This method can be called safely by any thread.

Assert that a boolean condition, described in <code>String</code> <code>message</code>, is true. If the condition is <code>true</code>, this method returns normally. Else, it throws <code>TestFailedException</code> with a helpful error message appended with the <code>String</code> obtained by invoking <code>toString</code> on the specified <code>clue</code> as the exception's detail message.

This method is implemented in terms of a Scala macro that will generate a more helpful error message for expressions of this form:

• assert(a == b, "a good clue")

• assert(a != b, "a good clue")

• assert(a === b, "a good clue")

• assert(a !== b, "a good clue")

• assert(a > b, "a good clue")

• assert(a >= b, "a good clue")

• assert(a < b, "a good clue")

• assert(a <= b, "a good clue")

• assert(a startsWith "prefix", "a good clue")

• assert(a endsWith "postfix", "a good clue")

• assert(a contains "something", "a good clue")

• assert(a eq b, "a good clue")

• assert(a ne b, "a good clue")

• assert(a > 0 && b > 5, "a good clue")

• assert(a > 0 || b > 5, "a good clue")

• assert(a.isEmpty, "a good clue")

• assert(!a.isEmpty, "a good clue")

• assert(a.isInstanceOf[String], "a good clue")

• assert(a.length == 8, "a good clue")

• assert(a.size == 8, "a good clue")

• assert(a.exists(_ == 8), "a good clue")

At this time, any other form of expression will just get a <code>TestFailedException</code> with message saying the given expression was false. In the future, we will enhance this macro to give helpful error messages in more situations. In ScalaTest 2.0, however, this behavior was sufficient to allow the <code>===</code> that returns <code>Boolean</code> to be the default in tests. This makes <code>===</code> consistent between tests and production code.

Assert that a boolean condition is true. If the condition is <code>true</code>, this method returns normally. Else, it throws <code>TestFailedException</code>.

This method is implemented in terms of a Scala macro that will generate a more helpful error message for expressions of this form:

• assert(a == b)

• assert(a != b)

• assert(a === b)

• assert(a !== b)

• assert(a > b)

• assert(a >= b)

• assert(a < b)

• assert(a <= b)

• assert(a startsWith "prefix")

• assert(a endsWith "postfix")

• assert(a contains "something")

• assert(a eq b)

• assert(a ne b)

• assert(a > 0 && b > 5)

• assert(a > 0 || b > 5)

• assert(a.isEmpty)

• assert(!a.isEmpty)

• assert(a.isInstanceOf[String])

• assert(a.length == 8)

• assert(a.size == 8)

• assert(a.exists(_ == 8))

At this time, any other form of expression will get a <code>TestFailedException</code> with message saying the given expression was false. In the future, we will enhance this macro to give helpful error messages in more situations. In ScalaTest 2.0, however, this behavior was sufficient to allow the <code>===</code> that returns <code>Boolean</code> to be the default in tests. This makes <code>===</code> consistent between tests and production code.

Asserts that a given string snippet of code passes both the Scala parser and type checker.

You can use this to make sure a snippet of code compiles:

<pre class="stHighlight"> assertCompiles("val a: Int = 1") </pre>

Although <code>assertCompiles</code> is implemented with a macro that determines at compile time whether the snippet of code represented by the passed string compiles, errors (<em>i.e.</em>, snippets of code that <em>do not</em> compile) are reported as test failures at runtime.

Asserts that a given string snippet of code does not pass either the Scala parser or type checker.

Often when creating libraries you may wish to ensure that certain arrangements of code that represent potential “user errors” do not compile, so that your library is more error resistant. ScalaTest's <code>Assertions</code> trait includes the following syntax for that purpose:

<pre class="stHighlight"> assertDoesNotCompile("val a: String = \"a string") </pre>

Although <code>assertDoesNotCompile</code> is implemented with a macro that determines at compile time whether the snippet of code represented by the passed string doesn't compile, errors (<em>i.e.</em>, snippets of code that <em>do</em> compile) are reported as test failures at runtime.

Note that the difference between <code>assertTypeError</code> and <code>assertDoesNotCompile</code> is that <code>assertDoesNotCompile</code> will succeed if the given code does not compile for any reason, whereas <code>assertTypeError</code> will only succeed if the given code does not compile because of a type error. If the given code does not compile because of a syntax error, for example, <code>assertDoesNotCompile</code> will return normally but <code>assertTypeError</code> will throw a <code>TestFailedException</code>.

Assert that the value passed as <code>expected</code> equals the value passed as <code>actual</code>. If the <code>actual</code> value equals the <code>expected</code> value (as determined by <code>==</code>), <code>assertResult</code> returns normally. Else, <code>assertResult</code> throws a <code>TestFailedException</code> whose detail message includes the expected and actual values.

Assert that the value passed as <code>expected</code> equals the value passed as <code>actual</code>. If the <code>actual</code> equals the <code>expected</code> (as determined by <code>==</code>), <code>assertResult</code> returns normally. Else, if <code>actual</code> is not equal to <code>expected</code>, <code>assertResult</code> throws a <code>TestFailedException</code> whose detail message includes the expected and actual values, as well as the <code>String</code> obtained by invoking <code>toString</code> on the passed <code>clue</code>.

Ensure that an expected exception is thrown by the passed function value. The thrown exception must be an instance of the type specified by the type parameter of this method. This method invokes the passed function. If the function throws an exception that's an instance of the specified type, this method returns <code>Succeeded</code>. Else, whether the passed function returns normally or completes abruptly with a different exception, this method throws <code>TestFailedException</code>.

Note that the type specified as this method's type parameter may represent any subtype of <code>AnyRef</code>, not just <code>Throwable</code> or one of its subclasses. In Scala, exceptions can be caught based on traits they implement, so it may at times make sense to specify a trait that the intercepted exception's class must mix in. If a class instance is passed for a type that could not possibly be used to catch an exception (such as <code>String</code>, for example), this method will complete abruptly with a <code>TestFailedException</code>.

Also note that the difference between this method and <code>intercept</code> is that this method does not return the expected exception, so it does not let you perform further assertions on that exception. Instead, this method returns <code>Succeeded</code>, which means it can serve as the last statement in an async- or safe-style suite. It also indicates to the reader of the code that nothing further is expected about the thrown exception other than its type. The recommended usage is to use <code>assertThrows</code> by default, <code>intercept</code> only when you need to inspect the caught exception further.

Asserts that a given string snippet of code does not pass the Scala type checker, failing if the given snippet does not pass the Scala parser.

Often when creating libraries you may wish to ensure that certain arrangements of code that represent potential “user errors” do not compile, so that your library is more error resistant. ScalaTest's <code>Assertions</code> trait includes the following syntax for that purpose:

<pre class="stHighlight"> assertTypeError("val a: String = 1") </pre>

Although <code>assertTypeError</code> is implemented with a macro that determines at compile time whether the snippet of code represented by the passed string type checks, errors (<em>i.e.</em>, snippets of code that <em>do</em> type check) are reported as test failures at runtime.

Note that the difference between <code>assertTypeError</code> and <code>assertDoesNotCompile</code> is that <code>assertDoesNotCompile</code> will succeed if the given code does not compile for any reason, whereas <code>assertTypeError</code> will only succeed if the given code does not compile because of a type error. If the given code does not compile because of a syntax error, for example, <code>assertDoesNotCompile</code> will return normally but <code>assertTypeError</code> will throw a <code>TestFailedException</code>.

Assume that a boolean condition, described in <code>String</code> <code>message</code>, is true. If the condition is <code>true</code>, this method returns normally. Else, it throws <code>TestCanceledException</code> with a helpful error message appended with <code>String</code> obtained by invoking <code>toString</code> on the specified <code>clue</code> as the exception's detail message.

This method is implemented in terms of a Scala macro that will generate a more helpful error message for expressions of this form:

• assume(a == b, "a good clue")

• assume(a != b, "a good clue")

• assume(a === b, "a good clue")

• assume(a !== b, "a good clue")

• assume(a > b, "a good clue")

• assume(a >= b, "a good clue")

• assume(a < b, "a good clue")

• assume(a <= b, "a good clue")

• assume(a startsWith "prefix", "a good clue")

• assume(a endsWith "postfix", "a good clue")

• assume(a contains "something", "a good clue")

• assume(a eq b, "a good clue")

• assume(a ne b, "a good clue")

• assume(a > 0 && b > 5, "a good clue")

• assume(a > 0 || b > 5, "a good clue")

• assume(a.isEmpty, "a good clue")

• assume(!a.isEmpty, "a good clue")

• assume(a.isInstanceOf[String], "a good clue")

• assume(a.length == 8, "a good clue")

• assume(a.size == 8, "a good clue")

• assume(a.exists(_ == 8), "a good clue")

At this time, any other form of expression will just get a <code>TestCanceledException</code> with message saying the given expression was false. In the future, we will enhance this macro to give helpful error messages in more situations. In ScalaTest 2.0, however, this behavior was sufficient to allow the <code>===</code> that returns <code>Boolean</code> to be the default in tests. This makes <code>===</code> consistent between tests and production code.

Assume that a boolean condition is true. If the condition is <code>true</code>, this method returns normally. Else, it throws <code>TestCanceledException</code>.

This method is implemented in terms of a Scala macro that will generate a more helpful error message for expressions of this form:

• assume(a == b)

• assume(a != b)

• assume(a === b)

• assume(a !== b)

• assume(a > b)

• assume(a >= b)

• assume(a < b)

• assume(a <= b)

• assume(a startsWith "prefix")

• assume(a endsWith "postfix")

• assume(a contains "something")

• assume(a eq b)

• assume(a ne b)

• assume(a > 0 && b > 5)

• assume(a > 0 || b > 5)

• assume(a.isEmpty)

• assume(!a.isEmpty)

• assume(a.isInstanceOf[String])

• assume(a.length == 8)

• assume(a.size == 8)

• assume(a.exists(_ == 8))

At this time, any other form of expression will just get a <code>TestCanceledException</code> with message saying the given expression was false. In the future, we will enhance this macro to give helpful error messages in more situations. In ScalaTest 2.0, however, this behavior was sufficient to allow the <code>===</code> that returns <code>Boolean</code> to be the default in tests. This makes <code>===</code> consistent between tests and production code.

Defines a method to be run before any of this suite's tests or nested suites are run.

This trait's implementation of <code>run</code> invokes this <code>beforeAll()</code> method. This trait's implementation of this method does nothing.

Throws <code>TestCanceledException</code>, with the passed <code>Throwable</code> cause, to indicate a test failed. The <code>getMessage</code> method of the thrown <code>TestCanceledException</code> will return <code>cause.toString</code>.

Throws <code>TestCanceledException</code>, with the passed <code>String</code> <code>message</code> as the exception's detail message and <code>Throwable</code> cause, to indicate a test failed.

Throws <code>TestCanceledException</code>, with the passed <code>String</code> <code>message</code> as the exception's detail message, to indicate a test was canceled.

Throws <code>TestCanceledException</code> to indicate a test was canceled.

Registers a block of code that produces any "futuristic" type (any type <code>F</code> for which an implicit <a href="enablers/Futuristic.html"><code>Futuristic[F]</code></a> instance is implicitly available), returning an object that offers a <code>lastly</code> method.

See the main documentation for trait <code>CompleteLastly</code> for more detail.

Returns an <code>Equality[A]</code> for any type <code>A</code> that determines equality by first calling <code>.deep</code> on any <code>Array</code> (on either the left or right side), then comparing the resulting objects with <code>==</code>.

Executes one or more tests in this <code>Suite</code>, printing results to the standard output.

This method invokes <code>run</code> on itself, passing in values that can be configured via the parameters to this method, all of which have default values. This behavior is convenient when working with ScalaTest in the Scala interpreter. Here's a summary of this method's parameters and how you can use them:

<strong>The <code>testName</code> parameter</strong>

If you leave <code>testName</code> at its default value (of <code>null</code>), this method will pass <code>None</code> to the <code>testName</code> parameter of <code>run</code>, and as a result all the tests in this suite will be executed. If you specify a <code>testName</code>, this method will pass <code>Some(testName)</code> to <code>run</code>, and only that test will be run. Thus to run all tests in a suite from the Scala interpreter, you can write:

<pre class="stREPL"> scala&gt; (new ExampleSuite).execute() </pre>

(The above syntax actually invokes the overloaded parameterless form of <code>execute</code>, which calls this form with its default parameter values.) To run just the test named <code>"my favorite test"</code> in a suite from the Scala interpreter, you would write:

<pre class="stREPL"> scala&gt; (new ExampleSuite).execute("my favorite test") </pre>

Or:

<pre class="stREPL"> scala&gt; (new ExampleSuite).execute(testName = "my favorite test") </pre>

<strong>The <code>configMap</code> parameter</strong>

If you provide a value for the <code>configMap</code> parameter, this method will pass it to <code>run</code>. If not, the default value of an empty <code>Map</code> will be passed. For more information on how to use a config map to configure your test suites, see the <a href="#configMapSection">config map section</a> in the main documentation for this trait. Here's an example in which you configure a run with the name of an input file:

<pre class="stREPL"> scala&gt; (new ExampleSuite).execute(configMap = Map("inputFileName" -&gt; "in.txt") </pre>

<strong>The <code>color</code> parameter</strong>

If you leave the <code>color</code> parameter unspecified, this method will configure the reporter it passes to <code>run</code> to print to the standard output in color (via ansi escape characters). If you don't want color output, specify false for <code>color</code>, like this:

<pre class="stREPL"> scala&gt; (new ExampleSuite).execute(color = false) </pre>

<strong>The <code>durations</code> parameter</strong>

If you leave the <code>durations</code> parameter unspecified, this method will configure the reporter it passes to <code>run</code> to <em>not</em> print durations for tests and suites to the standard output. If you want durations printed, specify true for <code>durations</code>, like this:

<pre class="stREPL"> scala&gt; (new ExampleSuite).execute(durations = true) </pre>

<strong>The <code>shortstacks</code> and <code>fullstacks</code> parameters</strong>

If you leave both the <code>shortstacks</code> and <code>fullstacks</code> parameters unspecified, this method will configure the reporter it passes to <code>run</code> to <em>not</em> print stack traces for failed tests if it has a stack depth that identifies the offending line of test code. If you prefer a short stack trace (10 to 15 stack frames) to be printed with any test failure, specify true for <code>shortstacks</code>:

<pre class="stREPL"> scala&gt; (new ExampleSuite).execute(shortstacks = true) </pre>

For full stack traces, set <code>fullstacks</code> to true:

<pre class="stREPL"> scala&gt; (new ExampleSuite).execute(fullstacks = true) </pre>

If you specify true for both <code>shortstacks</code> and <code>fullstacks</code>, you'll get full stack traces.

<strong>The <code>stats</code> parameter</strong>

If you leave the <code>stats</code> parameter unspecified, this method will <em>not</em> fire <code>RunStarting</code> and either <code>RunCompleted</code> or <code>RunAborted</code> events to the reporter it passes to <code>run</code>. If you specify true for <code>stats</code>, this method will fire the run events to the reporter, and the reporter will print the expected test count before the run, and various statistics after, including the number of suites completed and number of tests that succeeded, failed, were ignored or marked pending. Here's how you get the stats:

<pre class="stREPL"> scala&gt; (new ExampleSuite).execute(stats = true) </pre>

To summarize, this method will pass to <code>run</code>:

• <code>testName</code> - <code>None</code> if this method's <code>testName</code> parameter is left at its default value of <code>null</code>, else <code>Some(testName)</code>.

• <code>reporter</code> - a reporter that prints to the standard output

• <code>stopper</code> - a <code>Stopper</code> whose <code>apply</code> method always returns <code>false</code>

• <code>filter</code> - a <code>Filter</code> constructed with <code>None</code> for <code>tagsToInclude</code> and <code>Set()</code> for <code>tagsToExclude</code>

• <code>configMap</code> - the <code>configMap</code> passed to this method

• <code>distributor</code> - <code>None</code>

• <code>tracker</code> - a new <code>Tracker</code>

Note: In ScalaTest, the terms "execute" and "run" basically mean the same thing and can be used interchangably. The reason this method isn't named <code>run</code> is that it takes advantage of default arguments, and you can't mix overloaded methods and default arguments in Scala. (If named <code>run</code>, this method would have the same name but different arguments than the main <a href="#run"><code>run</code> method</a> that takes seven arguments. Thus it would overload and couldn't be used with default argument values.)

Design note: This method has two "features" that may seem unidiomatic. First, the default value of <code>testName</code> is <code>null</code>. Normally in Scala the type of <code>testName</code> would be <code>Option[String]</code> and the default value would be <code>None</code>, as it is in this trait's <code>run</code> method. The <code>null</code> value is used here for two reasons. First, in ScalaTest 1.5, <code>execute</code> was changed from four overloaded methods to one method with default values, taking advantage of the default and named parameters feature introduced in Scala 2.8. To not break existing source code, <code>testName</code> needed to have type <code>String</code>, as it did in two of the overloaded <code>execute</code> methods prior to 1.5. The other reason is that <code>execute</code> has always been designed to be called primarily from an interpeter environment, such as the Scala REPL (Read-Evaluate-Print-Loop). In an interpreter environment, minimizing keystrokes is king. A <code>String</code> type with a <code>null</code> default value lets users type <code>suite.execute("my test name")</code> rather than <code>suite.execute(Some("my test name"))</code>, saving several keystrokes.

The second non-idiomatic feature is that <code>shortstacks</code> and <code>fullstacks</code> are all lower case rather than camel case. This is done to be consistent with the <a href="Shell.html"><code>Shell</code></a>, which also uses those forms. The reason lower case is used in the <code>Shell</code> is to save keystrokes in an interpreter environment. Most Unix commands, for example, are all lower case, making them easier and quicker to type. In the ScalaTest <code>Shell</code>, methods like <code>shortstacks</code>, <code>fullstacks</code>, and <code>nostats</code>, <em>etc.</em>, are designed to be all lower case so they feel more like shell commands than methods.

The total number of tests that are expected to run when this <code>Suite</code>'s <code>run</code> method is invoked.

This trait's implementation of this method returns the sum of:

• the size of the <code>testNames</code> <code>List</code>, minus the number of tests marked as ignored and any tests that are exluded by the passed <code>Filter</code>

• the sum of the values obtained by invoking <code>expectedTestCount</code> on every nested <code>Suite</code> contained in <code>nestedSuites</code>

Throws <code>TestFailedException</code>, with the passed <code>Throwable</code> cause, to indicate a test failed. The <code>getMessage</code> method of the thrown <code>TestFailedException</code> will return <code>cause.toString</code>.

Throws <code>TestFailedException</code>, with the passed <code>String</code> <code>message</code> as the exception's detail message and <code>Throwable</code> cause, to indicate a test failed.

Throws <code>TestFailedException</code>, with the passed <code>String</code> <code>message</code> as the exception's detail message, to indicate a test failed.

Throws <code>TestFailedException</code> to indicate a test failed.

Register a test to ignore, which has the specified name, optional tags, and function value that takes no arguments. This method will register the test for later ignoring via an invocation of one of the <code>run</code> methods. This method exists to make it easy to ignore an existing test by changing the call to <code>test</code> to <code>ignore</code> without deleting or commenting out the actual test code. The test will not be run, but a report will be sent that indicates the test was ignored. The passed test name must not have been registered previously on this <code>AsyncFunSuite</code> instance.

Returns an <code>Informer</code> that during test execution will forward strings passed to its <code>apply</code> method to the current reporter. If invoked in a constructor, it will register the passed string for forwarding later during test execution. If invoked from inside a scope, it will forward the information to the current reporter immediately. If invoked from inside a test function, it will record the information and forward it to the current reporter only after the test completed, as <code>recordedEvents</code> of the test completed event, such as <code>TestSucceeded</code>. If invoked at any other time, it will print to the standard output. This method can be called safely by any thread.

Intercept and return an exception that's expected to be thrown by the passed function value. The thrown exception must be an instance of the type specified by the type parameter of this method. This method invokes the passed function. If the function throws an exception that's an instance of the specified type, this method returns that exception. Else, whether the passed function returns normally or completes abruptly with a different exception, this method throws <code>TestFailedException</code>.

Note that the type specified as this method's type parameter may represent any subtype of <code>AnyRef</code>, not just <code>Throwable</code> or one of its subclasses. In Scala, exceptions can be caught based on traits they implement, so it may at times make sense to specify a trait that the intercepted exception's class must mix in. If a class instance is passed for a type that could not possibly be used to catch an exception (such as <code>String</code>, for example), this method will complete abruptly with a <code>TestFailedException</code>.

Also note that the difference between this method and <code>assertThrows</code> is that this method returns the expected exception, so it lets you perform further assertions on that exception. By contrast, the <code>assertThrows</code> method returns <code>Succeeded</code>, which means it can serve as the last statement in an async- or safe-style suite. <code>assertThrows</code> also indicates to the reader of the code that nothing further is expected about the thrown exception other than its type. The recommended usage is to use <code>assertThrows</code> by default, <code>intercept</code> only when you need to inspect the caught exception further.

Returns a <code>Documenter</code> that during test execution will forward strings passed to its <code>apply</code> method to the current reporter. If invoked in a constructor, it will register the passed string for forwarding later during test execution. If invoked from inside a scope, it will forward the information to the current reporter immediately. If invoked from inside a test function, it will record the information and forward it to the current reporter only after the test completed, as <code>recordedEvents</code> of the test completed event, such as <code>TestSucceeded</code>. If invoked at any other time, it will print to the standard output. This method can be called safely by any thread.

An immutable <code>IndexedSeq</code> of this <code>Suite</code> object's nested <code>Suite</code>s. If this <code>Suite</code> contains no nested <code>Suite</code>s, this method returns an empty <code>IndexedSeq</code>. This trait's implementation of this method returns an empty <code>List</code>.

Returns a <code>Notifier</code> that during test execution will forward strings passed to its <code>apply</code> method to the current reporter. If invoked in a constructor, it will register the passed string for forwarding later during test execution. If invoked while this <code>AsyncFunSuite</code> is being executed, such as from inside a test function, it will forward the information to the current reporter immediately. If invoked at any other time, it will print to the standard output. This method can be called safely by any thread.

Throws <code>TestPendingException</code> to indicate a test is pending.

A <em>pending test</em> is one that has been given a name but is not yet implemented. The purpose of pending tests is to facilitate a style of testing in which documentation of behavior is sketched out before tests are written to verify that behavior (and often, the before the behavior of the system being tested is itself implemented). Such sketches form a kind of specification of what tests and functionality to implement later.

To support this style of testing, a test can be given a name that specifies one bit of behavior required by the system being tested. The test can also include some code that sends more information about the behavior to the reporter when the tests run. At the end of the test, it can call method <code>pending</code>, which will cause it to complete abruptly with <code>TestPendingException</code>. Because tests in ScalaTest can be designated as pending with <code>TestPendingException</code>, both the test name and any information sent to the reporter when running the test can appear in the report of a test run. (In other words, the code of a pending test is executed just like any other test.) However, because the test completes abruptly with <code>TestPendingException</code>, the test will be reported as pending, to indicate the actual test, and possibly the functionality it is intended to test, has not yet been implemented.

Note: This method always completes abruptly with a <code>TestPendingException</code>. Thus it always has a side effect. Methods with side effects are usually invoked with parentheses, as in <code>pending()</code>. This method is defined as a parameterless method, in flagrant contradiction to recommended Scala style, because it forms a kind of DSL for pending tests. It enables tests in suites such as <code>FunSuite</code> or <code>FunSpec</code> to be denoted by placing "<code>(pending)</code>" after the test name, as in:

<pre class="stHighlight"> test("that style rules are not laws") (pending) </pre>

Readers of the code see "pending" in parentheses, which looks like a little note attached to the test name to indicate it is pending. Whereas "<code>(pending())</code> looks more like a method call, "<code>(pending)</code>" lets readers stay at a higher level, forgetting how it is implemented and just focusing on the intent of the programmer who wrote the code.

Execute the passed block of code, and if it completes abruptly, throw <code>TestPendingException</code>, else throw <code>TestFailedException</code>.

This method can be used to temporarily change a failing test into a pending test in such a way that it will automatically turn back into a failing test once the problem originally causing the test to fail has been fixed. At that point, you need only remove the <code>pendingUntilFixed</code> call. In other words, a <code>pendingUntilFixed</code> surrounding a block of code that isn't broken is treated as a test failure. The motivation for this behavior is to encourage people to remove <code>pendingUntilFixed</code> calls when there are no longer needed.

This method facilitates a style of testing in which tests are written before the code they test. Sometimes you may encounter a test failure that requires more functionality than you want to tackle without writing more tests. In this case you can mark the bit of test code causing the failure with <code>pendingUntilFixed</code>. You can then write more tests and functionality that eventually will get your production code to a point where the original test won't fail anymore. At this point the code block marked with <code>pendingUntilFixed</code> will no longer throw an exception (because the problem has been fixed). This will in turn cause <code>pendingUntilFixed</code> to throw <code>TestFailedException</code> with a detail message explaining you need to go back and remove the <code>pendingUntilFixed</code> call as the problem orginally causing your test code to fail has been fixed.

Transforms a future of any type into a <code>Future[T]</code>, where <code>T</code> is a given expected exception type, which succeeds if the given future completes with a <code>Failure</code> containing the specified exception type.

See the main documentation for this trait for more detail and examples.

Transforms a future of any type into a <code>Future[Assertion]</code> that succeeds if the future completes with a <code>Failure</code> containing the specified exception type.

See the main documentation for this trait for more detail and examples.

The fully qualified class name of the rerunner to rerun this suite. This implementation will look at this.getClass and see if it is either an accessible Suite, or it has a WrapWith annotation. If so, it returns the fully qualified class name wrapped in a Some, or else it returns None.

Execute a suite surrounded by calls to <code>beforeAll</code> and <code>afterAll</code>.

This trait's implementation of this method ("this method") invokes <code>beforeAll(ConfigMap)</code> before executing any tests or nested suites and <code>afterAll(ConfigMap)</code> after executing all tests and nested suites. It runs the suite by invoking <code>super.run</code>, passing along the parameters passed to it.

If any invocation of <code>beforeAll</code> completes abruptly with an exception, this method will complete abruptly with the same exception. If any call to <code>super.run</code> completes abruptly with an exception, this method will complete abruptly with the same exception, however, before doing so, it will invoke <code>afterAll</code>. If <code>afterAll</code> <em>also</em> completes abruptly with an exception, this method will nevertheless complete abruptly with the exception previously thrown by <code>super.run</code>. If <code>super.run</code> returns normally, but <code>afterAll</code> completes abruptly with an exception, this method will complete abruptly with the same exception.

This method does not invoke either <code>beforeAll</code> or <code>afterAll</code> if <code>runTestsInNewInstance</code> is true so that any side effects only happen once per test if <code>OneInstancePerTest</code> is being used. In addition, if no tests are expected, then <code>beforeAll</code> and <code>afterAll</code> will be invoked only if the <code>invokeBeforeAllAndAfterAllEvenIfNoTestsAreExpected</code> flag is true. By default, this flag is false, so that if all tests are excluded (such as if the entire suite class has been marked with <code>@Ignore</code>), then side effects would happen only if at least one test will ultimately be executed in this suite or its nested suites.

Run a test. This trait's implementation runs the test registered with the name specified by <code>testName</code>.

Run zero to many of this <code>AsyncFunSuite</code>'s tests.

A string ID for this <code>Suite</code> that is intended to be unique among all suites reported during a run.

This trait's implementation of this method returns the fully qualified name of this object's class. Each suite reported during a run will commonly be an instance of a different <code>Suite</code> class, and in such cases, this default implementation of this method will suffice. However, in special cases you may need to override this method to ensure it is unique for each reported suite. For example, if you write a <code>Suite</code> subclass that reads in a file whose name is passed to its constructor and dynamically creates a suite of tests based on the information in that file, you will likely need to override this method in your <code>Suite</code> subclass, perhaps by appending the pathname of the file to the fully qualified class name. That way if you run a suite of tests based on a directory full of these files, you'll have unique suite IDs for each reported suite.

The suite ID is <em>intended</em> to be unique, because ScalaTest does not enforce that it is unique. If it is not unique, then you may not be able to uniquely identify a particular test of a particular suite. This ability is used, for example, to dynamically tag tests as having failed in the previous run when rerunning only failed tests.

A user-friendly suite name for this <code>Suite</code>.

This trait's implementation of this method returns the simple name of this object's class. This trait's implementation of <code>runNestedSuites</code> calls this method to obtain a name for <code>Report</code>s to pass to the <code>suiteStarting</code>, <code>suiteCompleted</code>, and <code>suiteAborted</code> methods of the <code>Reporter</code>.

A <code>Map</code> whose keys are <code>String</code> names of tagged tests and whose associated values are the <code>Set</code> of tags for the test. If this <code>AsyncFunSuite</code> contains no tags, this method returns an empty <code>Map</code>.

This trait's implementation returns tags that were passed as strings contained in <code>Tag</code> objects passed to methods <code>test</code> and <code>ignore</code>.

In addition, this trait's implementation will also auto-tag tests with class level annotations. For example, if you annotate <code>@Ignore</code> at the class level, all test methods in the class will be auto-annotated with <code>org.scalatest.Ignore</code>.

Register a test with the specified name, optional tags, and function value that takes no arguments. This method will register the test for later execution via an invocation of one of the <code>run</code> methods. The passed test name must not have been registered previously on this <code>AsyncFunSuite</code> instance.

An immutable <code>Set</code> of test names. If this <code>AsyncFunSuite</code> contains no tests, this method returns an empty <code>Set</code>.

This trait's implementation of this method will return a set that contains the names of all registered tests. The set's iterator will return those names in the order in which the tests were registered.

Registers shared tests.

This method enables the following syntax for shared tests in a <code>AsyncFunSuite</code>:

<pre class="stHighlight"> testsFor(nonEmptyStack(lastValuePushed)) </pre>

This method just provides syntax sugar intended to make the intent of the code clearer. Because the parameter passed to it is type <code>Unit</code>, the expression will be evaluated before being passed, which is sufficient to register the shared tests. For examples of shared tests, see the <a href="#sharedTests">Shared tests section</a> in the main documentation for this trait.

Returns a user friendly string for this suite, composed of the simple name of the class (possibly simplified further by removing dollar signs if added by the Scala interpeter) and, if this suite contains nested suites, the result of invoking <code>toString</code> on each of the nested suites, separated by commas and surrounded by parentheses.

Executes the block of code passed as the second parameter, and, if it completes abruptly with a <code>ModifiableMessage</code> exception, prepends the "clue" string passed as the first parameter to the beginning of the detail message of that thrown exception, then rethrows it. If clue does not end in a white space character, one space will be added between it and the existing detail message (unless the detail message is not defined).

This method allows you to add more information about what went wrong that will be reported when a test fails. Here's an example:

<pre class="stHighlight"> withClue("(Employee's name was: " + employee.name + ")") { intercept[IllegalArgumentException] { employee.getTask(-1) } } </pre>

If an invocation of <code>intercept</code> completed abruptly with an exception, the resulting message would be something like:

<pre> (Employee's name was Bob Jones) Expected IllegalArgumentException to be thrown, but no exception was thrown </pre>

Run the passed test function in the context of a fixture established by this method.

This method should set up the fixture needed by the tests of the current suite, invoke the test function, and if needed, register a callback on the resulting <code>FutureOutcome</code> to perform any clean up needed after the test completes. Because the <code>NoArgAsyncTest</code> function passed to this method takes no parameters, preparing the fixture will require side effects, such as reassigning instance <code>var</code>s in this <code>Suite</code> or initializing a globally accessible external database. If you want to avoid reassigning instance <code>var</code>s you can use <a href="FixtureAsyncTestSuite.html">FixtureAsyncTestSuite</a>.

This trait's implementation of <code>runTest</code> invokes this method for each test, passing in a <code>NoArgAsyncTest</code> whose <code>apply</code> method will execute the code of the test and returns its result.

This trait's implementation of this method simply invokes the passed <code>NoArgAsyncTest</code> function.

Trap and return any thrown exception that would normally cause a ScalaTest test to fail, or create and return a new <code>RuntimeException</code> indicating no exception is thrown.

This method is intended to be used in the Scala interpreter to eliminate large stack traces when trying out ScalaTest assertions and matcher expressions. It is not intended to be used in regular test code. If you want to ensure that a bit of code throws an expected exception, use <code>intercept</code>, not <code>trap</code>. Here's an example interpreter session without <code>trap</code>:

<pre class="stREPL"> scala&gt; import org.scalatest._ import org.scalatest._ scala&gt; import Matchers._ import Matchers._ scala&gt; val x = 12 a: Int = 12 scala&gt; x shouldEqual 13 org.scalatest.exceptions.TestFailedException: 12 did not equal 13 at org.scalatest.Assertions$class.newAssertionFailedException(Assertions.scala:449) at org.scalatest.Assertions$.newAssertionFailedException(Assertions.scala:1203) at org.scalatest.Assertions$AssertionsHelper.macroAssertTrue(Assertions.scala:417) at .&lt;init&gt;(&lt;console&gt;:15) at .&lt;clinit&gt;(&lt;console&gt;) at .&lt;init&gt;(&lt;console&gt;:7) at .&lt;clinit&gt;(&lt;console&gt;) at $print(&lt;console&gt;) at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method) at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:39) at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:25) at java.lang.reflect.Method.invoke(Method.java:597) at scala.tools.nsc.interpreter.IMain$ReadEvalPrint.call(IMain.scala:731) at scala.tools.nsc.interpreter.IMain$Request.loadAndRun(IMain.scala:980) at scala.tools.nsc.interpreter.IMain.loadAndRunReq$1(IMain.scala:570) at scala.tools.nsc.interpreter.IMain.interpret(IMain.scala:601) at scala.tools.nsc.interpreter.IMain.interpret(IMain.scala:565) at scala.tools.nsc.interpreter.ILoop.reallyInterpret$1(ILoop.scala:745) at scala.tools.nsc.interpreter.ILoop.interpretStartingWith(ILoop.scala:790) at scala.tools.nsc.interpreter.ILoop.command(ILoop.scala:702) at scala.tools.nsc.interpreter.ILoop.processLine$1(ILoop.scala:566) at scala.tools.nsc.interpreter.ILoop.innerLoop$1(ILoop.scala:573) at scala.tools.nsc.interpreter.ILoop.loop(ILoop.scala:576) at scala.tools.nsc.interpreter.ILoop$$anonfun$process$1.apply$mcZ$sp(ILoop.scala:867) at scala.tools.nsc.interpreter.ILoop$$anonfun$process$1.apply(ILoop.scala:822) at scala.tools.nsc.interpreter.ILoop$$anonfun$process$1.apply(ILoop.scala:822) at scala.tools.nsc.util.ScalaClassLoader$.savingContextLoader(ScalaClassLoader.scala:135) at scala.tools.nsc.interpreter.ILoop.process(ILoop.scala:822) at scala.tools.nsc.MainGenericRunner.runTarget$1(MainGenericRunner.scala:83) at scala.tools.nsc.MainGenericRunner.process(MainGenericRunner.scala:96) at scala.tools.nsc.MainGenericRunner$.main(MainGenericRunner.scala:105) at scala.tools.nsc.MainGenericRunner.main(MainGenericRunner.scala) </pre>

That's a pretty tall stack trace. Here's what it looks like when you use <code>trap</code>:

<pre class="stREPL"> scala&gt; trap { x shouldEqual 13 } res1: Throwable = org.scalatest.exceptions.TestFailedException: 12 did not equal 13 </pre>

Much less clutter. Bear in mind, however, that if <em>no</em> exception is thrown by the passed block of code, the <code>trap</code> method will create a new <a href="Assertions$$NormalResult.html"><code>NormalResult</code></a> (a subclass of <code>Throwable</code> made for this purpose only) and return that. If the result was the <code>Unit</code> value, it will simply say that no exception was thrown:

<pre class="stREPL"> scala&gt; trap { x shouldEqual 12 } res2: Throwable = No exception was thrown. </pre>

If the passed block of code results in a value other than <code>Unit</code>, the <code>NormalResult</code>'s <code>toString</code> will print the value:

<pre class="stREPL"> scala&gt; trap { "Dude!" } res3: Throwable = No exception was thrown. Instead, result was: "Dude!" </pre>

Although you can access the result value from the <code>NormalResult</code>, its type is <code>Any</code> and therefore not very convenient to use. It is not intended that <code>trap</code> be used in test code. The sole intended use case for <code>trap</code> is decluttering Scala interpreter sessions by eliminating stack traces when executing assertion and matcher expressions.

Flag to indicate whether to invoke beforeAll and afterAll even when there are no tests expected.

The default value is <code>false</code>, which means beforeAll and afterAll will not be invoked if there are no tests expected. Whether tests are expected is determined by invoking <code>expectedTestCount</code> passing in the passed filter. Because this count does not include tests excluded based on tags, such as ignored tests, this prevents any side effects in <code>beforeAll</code> or <code>afterAll</code> if no tests will ultimately be executed anyway. If you always want to see the side effects even if no tests are expected, override this <code>val</code> and set it to true.

The <code>Succeeded</code> singleton.

You can use <code>succeed</code> to solve a type error when an async test does not end in either <code>Future[Assertion]</code> or <code>Assertion</code>. Because <code>Assertion</code> is a type alias for <code>Succeeded.type</code>, putting <code>succeed</code> at the end of a test body (or at the end of a function being used to map the final future of a test body) will solve the type error.

<strong>The <code>styleName</code> lifecycle method has been deprecated and will be removed in a future version of ScalaTest.</strong>

This method was used to support the chosen styles feature, which was deactivated in 3.1.0. The internal modularization of ScalaTest in 3.2.0 will replace chosen styles as the tool to encourage consistency across a project. We do not plan a replacement for <code>styleName</code>.

Implicitly converts an <code>Assertion</code> to a <code>Future[Assertion]</code>.

This implicit conversion is used to allow synchronous tests to be included along with asynchronous tests in an <code>AsyncTestSuite</code>. It will be