| <p><strong>TODO: Add more examples to cover all of the syntax.</strong></p> |
| <h1>Regressions</h1> |
| <p>Bad backtracking in the HR parser:</p> |
| <p>-------------------------- | -------------------------------------------------</p> |
| <h1>Real-world sample</h1> |
| <p>This input was taken from the test package's README to get a representative |
| sample of real-world markdown:</p> |
| <p>Tests are specified using the top-level <a href="https://pub.dev/documentation/test_core/latest/test_core/test.html"><code>test()</code></a> function, and test |
| assertions are made using <a href="https://pub.dev/documentation/test_api/latest/test_api/expect.html"><code>expect()</code></a>:</p> |
| <pre><code class="language-dart">import "package:test/test.dart"; |
| |
| void main() { |
| test("String.split() splits the string on the delimiter", () { |
| var string = "foo,bar,baz"; |
| expect(string.split(","), equals(["foo", "bar", "baz"])); |
| }); |
| |
| test("String.trim() removes surrounding whitespace", () { |
| var string = " foo "; |
| expect(string.trim(), equals("foo")); |
| }); |
| } |
| </code></pre> |
| <p>Tests can be grouped together using the [<code>group()</code>] function. Each group's |
| description is added to the beginning of its test's descriptions.</p> |
| <pre><code class="language-dart">import "package:test/test.dart"; |
| |
| void main() { |
| group("String", () { |
| test(".split() splits the string on the delimiter", () { |
| var string = "foo,bar,baz"; |
| expect(string.split(","), equals(["foo", "bar", "baz"])); |
| }); |
| |
| test(".trim() removes surrounding whitespace", () { |
| var string = " foo "; |
| expect(string.trim(), equals("foo")); |
| }); |
| }); |
| |
| group("int", () { |
| test(".remainder() returns the remainder of division", () { |
| expect(11.remainder(3), equals(2)); |
| }); |
| |
| test(".toRadixString() returns a hex string", () { |
| expect(11.toRadixString(16), equals("b")); |
| }); |
| }); |
| } |
| </code></pre> |
| <p>Any matchers from the <a href="https://pub.dev/documentation/matcher/latest/matcher/matcher-library.html"><code>matcher</code></a> package can be used with <code>expect()</code> |
| to do complex validations:</p> |
| <pre><code class="language-dart">import "package:test/test.dart"; |
| |
| void main() { |
| test(".split() splits the string on the delimiter", () { |
| expect("foo,bar,baz", allOf([ |
| contains("foo"), |
| isNot(startsWith("bar")), |
| endsWith("baz") |
| ])); |
| }); |
| } |
| </code></pre> |
| <h2>Running Tests</h2> |
| <p>A single test file can be run just using <code>pub run test:test path/to/test.dart</code> |
| (on Dart 1.10, this can be shortened to <code>pub run test path/to/test.dart</code>).</p> |
| <p><img src="https://raw.githubusercontent.com/dart-lang/test/master/image/test1.gif" alt="Single file being run via pub run"" /></p> |
| <p>Many tests can be run at a time using <code>pub run test:test path/to/dir</code>.</p> |
| <p><img src="https://raw.githubusercontent.com/dart-lang/test/master/image/test2.gif" alt="Directory being run via "pub run"." /></p> |
| <p>It's also possible to run a test on the Dart VM only by invoking it using <code>dart path/to/test.dart</code>, but this doesn't load the full test runner and will be |
| missing some features.</p> |
| <p>The test runner considers any file that ends with <code>_test.dart</code> to be a test |
| file. If you don't pass any paths, it will run all the test files in your |
| <code>test/</code> directory, making it easy to test your entire application at once.</p> |
| <p>By default, tests are run in the Dart VM, but you can run them in the browser as |
| well by passing <code>pub run test:test -p chrome path/to/test.dart</code>. |
| <code>test</code> will take care of starting the browser and loading the tests, and all |
| the results will be reported on the command line just like for VM tests. In |
| fact, you can even run tests on both platforms with a single command: <code>pub run test:test -p "chrome,vm" path/to/test.dart</code>.</p> |
| <h3>Restricting Tests to Certain Platforms</h3> |
| <p>Some test files only make sense to run on particular platforms. They may use |
| <code>dart:html</code> or <code>dart:io</code>, they might test Windows' particular filesystem |
| behavior, or they might use a feature that's only available in Chrome. The |
| <a href="https://pub.dev/documentation/test_api/latest/test_api/TestOn-class.html"><code>@TestOn</code></a> annotation makes it easy to declare exactly which platforms |
| a test file should run on. Just put it at the top of your file, before any |
| <code>library</code> or <code>import</code> declarations:</p> |
| <pre><code class="language-dart">@TestOn("vm") |
| |
| import "dart:io"; |
| |
| import "package:test/test.dart"; |
| |
| void main() { |
| // ... |
| } |
| </code></pre> |
| <p>The string you pass to <code>@TestOn</code> is what's called a "platform selector", and it |
| specifies exactly which platforms a test can run on. It can be as simple as the |
| name of a platform, or a more complex Dart-like boolean expression involving |
| these platform names.</p> |
| <h3>Platform Selector Syntax</h3> |
| <p>Platform selectors can contain identifiers, parentheses, and operators. When |
| loading a test, each identifier is set to <code>true</code> or <code>false</code> based on the current |
| platform, and the test is only loaded if the platform selector returns <code>true</code>. |
| The operators <code>||</code>, <code>&&</code>, <code>!</code>, and <code>? :</code> all work just like they do in Dart. The |
| valid identifiers are:</p> |
| <ul> |
| <li> |
| <p><code>vm</code>: Whether the test is running on the command-line Dart VM.</p> |
| </li> |
| <li> |
| <p><code>dartium</code>: Whether the test is running on Dartium.</p> |
| </li> |
| <li> |
| <p><code>content-shell</code>: Whether the test is running on the headless Dartium content |
| shell.</p> |
| </li> |
| <li> |
| <p><code>chrome</code>: Whether the test is running on Google Chrome.</p> |
| </li> |
| <li> |
| <p><code>phantomjs</code>: Whether the test is running on |
| <a href="http://phantomjs.org/">PhantomJS</a>.</p> |
| </li> |
| <li> |
| <p><code>firefox</code>: Whether the test is running on Mozilla Firefox.</p> |
| </li> |
| <li> |
| <p><code>safari</code>: Whether the test is running on Apple Safari.</p> |
| </li> |
| <li> |
| <p><code>ie</code>: Whether the test is running on Microsoft Internet Explorer.</p> |
| </li> |
| <li> |
| <p><code>dart-vm</code>: Whether the test is running on the Dart VM in any context, |
| including Dartium. It's identical to <code>!js</code>.</p> |
| </li> |
| <li> |
| <p><code>browser</code>: Whether the test is running in any browser.</p> |
| </li> |
| <li> |
| <p><code>js</code>: Whether the test has been compiled to JS. This is identical to |
| <code>!dart-vm</code>.</p> |
| </li> |
| <li> |
| <p><code>blink</code>: Whether the test is running in a browser that uses the Blink |
| rendering engine.</p> |
| </li> |
| <li> |
| <p><code>windows</code>: Whether the test is running on Windows. If <code>vm</code> is false, this will |
| be <code>false</code> as well.</p> |
| </li> |
| <li> |
| <p><code>mac-os</code>: Whether the test is running on Mac OS. If <code>vm</code> is false, this will |
| be <code>false</code> as well.</p> |
| </li> |
| <li> |
| <p><code>linux</code>: Whether the test is running on Linux. If <code>vm</code> is false, this will be |
| <code>false</code> as well.</p> |
| </li> |
| <li> |
| <p><code>android</code>: Whether the test is running on Android. If <code>vm</code> is false, this will |
| be <code>false</code> as well, which means that this <em>won't</em> be true if the test is |
| running on an Android browser.</p> |
| </li> |
| <li> |
| <p><code>posix</code>: Whether the test is running on a POSIX operating system. This is |
| equivalent to <code>!windows</code>.</p> |
| </li> |
| </ul> |
| <p>For example, if you wanted to run a test on every browser but Chrome, you would |
| write <code>@TestOn("browser && !chrome")</code>.</p> |
| <h3>Running Tests on Dartium</h3> |
| <p>Tests can be run on <a href="https://www.dartlang.org/tools/dartium/">Dartium</a> by passing the <code>-p dartium</code> flag. If you're |
| using the Dart Editor, the test runner will be able to find Dartium |
| automatically. On Mac OS, you can also <a href="https://github.com/dart-lang/homebrew-dart">install it using Homebrew</a>. |
| Otherwise, make sure there's an executable called <code>dartium</code> (on Mac OS or Linux) |
| or <code>dartium.exe</code> (on Windows) on your system path.</p> |
| <p>Similarly, tests can be run on the headless Dartium content shell by passing <code>-p content-shell</code>. The content shell is installed along with Dartium when using |
| Homebrew. Otherwise, you can downloaded it manually <a href="http://gsdview.appspot.com/dart-archive/channels/stable/release/latest/dartium/">from this |
| page</a>; if you do, make sure the executable named <code>content_shell</code> |
| (on Mac OS or Linux) or <code>content_shell.exe</code> (on Windows) is on your system path.</p> |
| <p><a href="https://github.com/dart-lang/test/issues/63">In the future</a>, there will be a more explicit way to configure the |
| location of both the Dartium and content shell executables.</p> |
| <h2>Asynchronous Tests</h2> |
| <p>Tests written with <code>async</code>/<code>await</code> will work automatically. The test runner |
| won't consider the test finished until the returned <code>Future</code> completes.</p> |
| <pre><code class="language-dart">import "dart:async"; |
| |
| import "package:test/test.dart"; |
| |
| void main() { |
| test("new Future.value() returns the value", () async { |
| var value = await new Future.value(10); |
| expect(value, equals(10)); |
| }); |
| } |
| </code></pre> |
| <p>There are also a number of useful functions and matchers for more advanced |
| asynchrony. The <a href="https://pub.dev/documentation/test_api/latest/test_api/completion.html"><code>completion()</code></a> matcher can be used to test |
| <code>Futures</code>; it ensures that the test doesn't finish until the <code>Future</code> completes, |
| and runs a matcher against that <code>Future</code>'s value.</p> |
| <pre><code class="language-dart">import "dart:async"; |
| |
| import "package:test/test.dart"; |
| |
| void main() { |
| test("new Future.value() returns the value", () { |
| expect(new Future.value(10), completion(equals(10))); |
| }); |
| } |
| </code></pre> |
| <p>The <a href="https://pub.dev/documentation/test_api/latest/test_api/throwsA.html"><code>throwsA()</code></a> matcher and the various <code>throwsExceptionType</code> |
| matchers work with both synchronous callbacks and asynchronous <code>Future</code>s. They |
| ensure that a particular type of exception is thrown:</p> |
| <pre><code class="language-dart">import "dart:async"; |
| |
| import "package:test/test.dart"; |
| |
| void main() { |
| test("new Future.error() throws the error", () { |
| expect(new Future.error("oh no"), throwsA(equals("oh no"))); |
| expect(new Future.error(new StateError("bad state")), throwsStateError); |
| }); |
| } |
| </code></pre> |
| <p>The <a href="https://pub.dev/documentation/test_api/latest/test_api/expectAsync.html"><code>expectAsync()</code></a> function wraps another function and has two |
| jobs. First, it asserts that the wrapped function is called a certain number of |
| times, and will cause the test to fail if it's called too often; second, it |
| keeps the test from finishing until the function is called the requisite number |
| of times.</p> |
| <pre><code class="language-dart">import "dart:async"; |
| |
| import "package:test/test.dart"; |
| |
| void main() { |
| test("Stream.fromIterable() emits the values in the iterable", () { |
| var stream = new Stream.fromIterable([1, 2, 3]); |
| |
| stream.listen(expectAsync((number) { |
| expect(number, inInclusiveRange(1, 3)); |
| }, count: 3)); |
| }); |
| } |
| </code></pre> |
| <h2>Running Tests with Custom HTML</h2> |
| <p>By default, the test runner will generate its own empty HTML file for browser |
| tests. However, tests that need custom HTML can create their own files. These |
| files have three requirements:</p> |
| <ul> |
| <li> |
| <p>They must have the same name as the test, with <code>.dart</code> replaced by <code>.html</code>.</p> |
| </li> |
| <li> |
| <p>They must contain a <code>link</code> tag with <code>rel="x-dart-test"</code> and an <code>href</code> |
| attribute pointing to the test script.</p> |
| </li> |
| <li> |
| <p>They must contain <code><script src="packages/test/dart.js"></script></code>.</p> |
| </li> |
| </ul> |
| <p>For example, if you had a test called <code>custom_html_test.dart</code>, you might write |
| the following HTML file:</p> |
| <pre><code class="language-html"><!doctype html> |
| <!-- custom_html_test.html --> |
| <html> |
| <head> |
| <title>Custom HTML Test</title> |
| <link rel="x-dart-test" href="custom_html_test.dart"> |
| <script src="packages/test/dart.js"></script> |
| </head> |
| <body> |
| // ... |
| </body> |
| </html> |
| </code></pre> |
| <h2>Configuring Tests</h2> |
| <h3>Skipping Tests</h3> |
| <p>If a test, group, or entire suite isn't working yet and you just want it to stop |
| complaining, you can mark it as "skipped". The test or tests won't be run, and, |
| if you supply a reason why, that reason will be printed. In general, skipping |
| tests indicates that they should run but is temporarily not working. If they're |
| is fundamentally incompatible with a platform, <a href="https://pub.dev/documentation/test_api/latest/test_api/TestOn-class.html"><code>@TestOn</code>/<code>testOn</code></a> |
| should be used instead.</p> |
| <p>To skip a test suite, put a <code>@Skip</code> annotation at the top of the file:</p> |
| <pre><code class="language-dart">@Skip("currently failing (see issue 1234)") |
| |
| import "package:test/test.dart"; |
| |
| void main() { |
| // ... |
| } |
| </code></pre> |
| <p>The string you pass should describe why the test is skipped. You don't have to |
| include it, but it's a good idea to document why the test isn't running.</p> |
| <p>Groups and individual tests can be skipped by passing the <code>skip</code> parameter. This |
| can be either <code>true</code> or a String describing why the test is skipped. For example:</p> |
| <pre><code class="language-dart">import "package:test/test.dart"; |
| |
| void main() { |
| group("complicated algorithm tests", () { |
| // ... |
| }, skip: "the algorithm isn't quite right"); |
| |
| test("error-checking test", () { |
| // ... |
| }, skip: "TODO: add error-checking."); |
| } |
| </code></pre> |
| <h3>Timeouts</h3> |
| <p>By default, tests will time out after 30 seconds of inactivity. However, this |
| can be configured on a per-test, -group, or -suite basis. To change the timeout |
| for a test suite, put a <code>@Timeout</code> annotation at the top of the file:</p> |
| <pre><code class="language-dart">@Timeout(const Duration(seconds: 45)) |
| |
| import "package:test/test.dart"; |
| |
| void main() { |
| // ... |
| } |
| </code></pre> |
| <p>In addition to setting an absolute timeout, you can set the timeout relative to |
| the default using <code>@Timeout.factor</code>. For example, <code>@Timeout.factor(1.5)</code> will |
| set the timeout to one and a half times as long as the default—45 seconds.</p> |
| <p>Timeouts can be set for tests and groups using the <code>timeout</code> parameter. This |
| parameter takes a <code>Timeout</code> object just like the annotation. For example:</p> |
| <pre><code class="language-dart">import "package:test/test.dart"; |
| |
| void main() { |
| group("slow tests", () { |
| // ... |
| |
| test("even slower test", () { |
| // ... |
| }, timeout: new Timeout.factor(2)) |
| }, timeout: new Timeout(new Duration(minutes: 1))); |
| } |
| </code></pre> |
| <p>Nested timeouts apply in order from outermost to innermost. That means that |
| "even slower test" will take two minutes to time out, since it multiplies the |
| group's timeout by 2.</p> |
| <h3>Platform-Specific Configuration</h3> |
| <p>Sometimes a test may need to be configured differently for different platforms. |
| Windows might run your code slower than other platforms, or your DOM |
| manipulation might not work right on Safari yet. For these cases, you can use |
| the <code>@OnPlatform</code> annotation and the <code>onPlatform</code> named parameter to <code>test()</code> |
| and <code>group()</code>. For example:</p> |
| <pre><code class="language-dart">@OnPlatform(const { |
| // Give Windows some extra wiggle-room before timing out. |
| "windows": const Timeout.factor(2) |
| }) |
| |
| import "package:test/test.dart"; |
| |
| void main() { |
| test("do a thing", () { |
| // ... |
| }, onPlatform: { |
| "safari": new Skip("Safari is currently broken (see #1234)") |
| }); |
| } |
| </code></pre> |
| <p>Both the annotation and the parameter take a map. The map's keys are <a href="#platform-selector-syntax">platform |
| selectors</a> which describe the platforms for which the |
| specialized configuration applies. Its values are instances of some of the same |
| annotation classes that can be used for a suite: <code>Skip</code> and <code>Timeout</code>. A value |
| can also be a list of these values.</p> |
| <p>If multiple platforms match, the configuration is applied in order from first to |
| last, just as they would in nested groups. This means that for configuration |
| like duration-based timeouts, the last matching value wins.</p> |
| <h2>Testing With <code>barback</code></h2> |
| <p>Packages using the <code>barback</code> transformer system may need to test code that's |
| created or modified using transformers. The test runner handles this using the |
| <code>--pub-serve</code> option, which tells it to load the test code from a <code>pub serve</code> |
| instance rather than from the filesystem.</p> |
| <p>Before using the <code>--pub-serve</code> option, add the <code>test/pub_serve</code> transformer to |
| your <code>pubspec.yaml</code>. This transformer adds the necessary bootstrapping code that |
| allows the test runner to load your tests properly:</p> |
| <pre><code class="language-yaml">transformers: |
| - test/pub_serve: |
| $include: test/**_test{.*,}.dart |
| </code></pre> |
| <p>Note that if you're using the test runner along with <a href="https://www.dartlang.org/polymer/"><code>polymer</code></a>, you |
| have to make sure that the <code>test/pub_serve</code> transformer comes <em>after</em> the |
| <code>polymer</code> transformer:</p> |
| <pre><code class="language-yaml">transformers: |
| - polymer |
| - test/pub_serve: |
| $include: test/**_test{.*,}.dart |
| </code></pre> |
| <p>Then, start up <code>pub serve</code>. Make sure to pay attention to which port it's using |
| to serve your <code>test/</code> directory:</p> |
| <pre><code class="language-shell">$ pub serve |
| Loading source assets... |
| Loading test/pub_serve transformers... |
| Serving my_app web on http://localhost:8080 |
| Serving my_app test on http://localhost:8081 |
| Build completed successfully |
| </code></pre> |
| <p>In this case, the port is <code>8081</code>. In another terminal, pass this port to |
| <code>--pub-serve</code> and otherwise invoke <code>pub run test:test</code> as normal:</p> |
| <pre><code class="language-shell">$ pub run test:test --pub-serve=8081 -p chrome |
| "pub serve" is compiling test/my_app_test.dart... |
| "pub serve" is compiling test/utils_test.dart... |
| 00:00 +42: All tests passed! |
| </code></pre> |