commit | 5b387b5cc612f02937fd5c1d88ea431c8bf25c44 | [log] [tgz] |
---|---|---|
author | Natalie Weizenbaum <nweiz@google.com> | Tue Mar 31 18:10:43 2015 -0700 |
committer | Natalie Weizenbaum <nweiz@google.com> | Tue Mar 31 18:10:43 2015 -0700 |
tree | 94ab10a58a2cc3836f232ea093a66ddb0672c895 | |
parent | 0d5c09b502e03dacc2b92c74f579214843dd06a5 [diff] |
Move the executable's implementation into lib. R=kevmoo@google.com Review URL: https://codereview.chromium.org//1049903002
test
provides a standard way of writing and running tests in Dart.
Tests are specified using the top-level test()
function, and test assertions are made using expect()
:
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")); }); }
Tests can be grouped together using the [group()
] function. Each group‘s description is added to the beginning of its test’s descriptions.
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")); }); }); }
Any matchers from the matcher
package can be used with expect()
to do complex validations:
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") ])); }); }
A single test file can be run just using dart path/to/test.dart
.
Many tests can be run at a time using pub run test:test path/to/dir
.
test
considers any file that ends with _test.dart
to be a test file. If you don't pass any paths, it will run all the test files in your test/
directory, making it easy to test your entire application at once.
By default, tests are run in the Dart VM, but you can run them in the browser as well by passing pub run test:test -p chrome path/to/test.dart
. test
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: pub run test:test -p chrome -p vm path/to/test.dart
.
Some test files only make sense to run on particular platforms. They may use dart:html
or dart:io
, they might test Windows' particular filesystem behavior, or they might use a feature that's only available in Chrome. The @TestOn
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 library
or import
declarations:
@TestOn("vm") import "dart:io"; import "package:test/test.dart"; void main() { // ... }
The string you pass to @TestOn
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.
Platform selectors can contain identifiers, parentheses, and operators. When loading a test, each identifier is set to true
or false
based on the current platform, and the test is only loaded if the platform selector returns true
. The operators ||
, &&
, !
, and ? :
all work just like they do in Dart. The valid identifiers are:
vm
: Whether the test is running on the command-line Dart VM.
chrome
: Whether the test is running on Google Chrome.
dart-vm
: Whether the test is running on the Dart VM in any context. For now this is identical to vm
, but it will also be true for Dartium in the future. It's identical to !js
.
browser
: Whether the test is running in any browser.
js
: Whether the test has been compiled to JS. This is identical to !dart-vm
.
blink
: Whether the test is running in a browser that uses the Blink rendering engine.
windows
: Whether the test is running on Windows. If vm
is false, this will be false
as well.
mac-os
: Whether the test is running on Mac OS. If vm
is false, this will be false
as well.
linux
: Whether the test is running on Linux. If vm
is false, this will be false
as well.
android
: Whether the test is running on Android. If vm
is false, this will be false
as well, which means that this won't be true if the test is running on an Android browser.
posix
: Whether the test is running on a POSIX operating system. This is equivalent to !windows
.
For example, if you wanted to run a test on every browser but Chrome, you would write @TestOn("browser && !chrome")
.
Tests written with async
/await
will work automatically. The test runner won't consider the test finished until the returned Future
completes.
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)); }); }
There are also a number of useful functions and matchers for more advanced asynchrony. The completion()
matcher can be used to test Futures
; it ensures that the test doesn't finish until the Future
completes, and runs a matcher against that Future
's value.
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))); }); }
The [throwsA()
][throwsA] matcher and the various throwsExceptionType
matchers work with both synchronous callbacks and asynchronous Future
s. They ensure that a particular type of exception is thrown:
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); }); }
The expectAsync()
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.
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)); }); }