| OLD | NEW |
| 1 `unittest` provides a standard way of writing and running tests in Dart. | 1 `test` provides a standard way of writing and running tests in Dart. |
| 2 | 2 |
| 3 ## Writing Tests | 3 ## Writing Tests |
| 4 | 4 |
| 5 Tests are specified using the top-level [`test()`][test] function, and test | 5 Tests are specified using the top-level [`test()`][test] function, and test |
| 6 assertions are made using [`expect()`][expect]: | 6 assertions are made using [`expect()`][expect]: |
| 7 | 7 |
| 8 [test]: http://www.dartdocs.org/documentation/unittest/latest/index.html#unittes
t/unittest@id_test | 8 [test]: http://www.dartdocs.org/documentation/test/latest/index.html#test/test@i
d_test |
| 9 [expect]: http://www.dartdocs.org/documentation/unittest/latest/index.html#unitt
est/unittest@id_expect | 9 [expect]: http://www.dartdocs.org/documentation/test/latest/index.html#test/test
@id_expect |
| 10 | 10 |
| 11 ```dart | 11 ```dart |
| 12 import "package:unittest/unittest.dart"; | 12 import "package:test/test.dart"; |
| 13 | 13 |
| 14 void main() { | 14 void main() { |
| 15 test("String.split() splits the string on the delimiter", () { | 15 test("String.split() splits the string on the delimiter", () { |
| 16 var string = "foo,bar,baz"; | 16 var string = "foo,bar,baz"; |
| 17 expect(string.split(","), equals(["foo", "bar", "baz"])); | 17 expect(string.split(","), equals(["foo", "bar", "baz"])); |
| 18 }); | 18 }); |
| 19 | 19 |
| 20 test("String.trim() removes surrounding whitespace", () { | 20 test("String.trim() removes surrounding whitespace", () { |
| 21 var string = " foo "; | 21 var string = " foo "; |
| 22 expect(string.trim(), equals("foo")); | 22 expect(string.trim(), equals("foo")); |
| 23 }); | 23 }); |
| 24 } | 24 } |
| 25 ``` | 25 ``` |
| 26 | 26 |
| 27 Tests can be grouped together using the [`group()`] function. Each group's | 27 Tests can be grouped together using the [`group()`] function. Each group's |
| 28 description is added to the beginning of its test's descriptions. | 28 description is added to the beginning of its test's descriptions. |
| 29 | 29 |
| 30 ```dart | 30 ```dart |
| 31 import "package:unittest/unittest.dart"; | 31 import "package:test/test.dart"; |
| 32 | 32 |
| 33 void main() { | 33 void main() { |
| 34 group("String", () { | 34 group("String", () { |
| 35 test(".split() splits the string on the delimiter", () { | 35 test(".split() splits the string on the delimiter", () { |
| 36 var string = "foo,bar,baz"; | 36 var string = "foo,bar,baz"; |
| 37 expect(string.split(","), equals(["foo", "bar", "baz"])); | 37 expect(string.split(","), equals(["foo", "bar", "baz"])); |
| 38 }); | 38 }); |
| 39 | 39 |
| 40 test(".trim() removes surrounding whitespace", () { | 40 test(".trim() removes surrounding whitespace", () { |
| 41 var string = " foo "; | 41 var string = " foo "; |
| (...skipping 12 matching lines...) Expand all Loading... |
| 54 }); | 54 }); |
| 55 } | 55 } |
| 56 ``` | 56 ``` |
| 57 | 57 |
| 58 Any matchers from the [`matcher`][matcher] package can be used with `expect()` | 58 Any matchers from the [`matcher`][matcher] package can be used with `expect()` |
| 59 to do complex validations: | 59 to do complex validations: |
| 60 | 60 |
| 61 [matcher]: http://www.dartdocs.org/documentation/matcher/latest/index.html#match
er/matcher | 61 [matcher]: http://www.dartdocs.org/documentation/matcher/latest/index.html#match
er/matcher |
| 62 | 62 |
| 63 ```dart | 63 ```dart |
| 64 import "package:unittest/unittest.dart"; | 64 import "package:test/test.dart"; |
| 65 | 65 |
| 66 void main() { | 66 void main() { |
| 67 test(".split() splits the string on the delimiter", () { | 67 test(".split() splits the string on the delimiter", () { |
| 68 expect("foo,bar,baz", allOf([ | 68 expect("foo,bar,baz", allOf([ |
| 69 contains("foo"), | 69 contains("foo"), |
| 70 isNot(startsWith("bar")), | 70 isNot(startsWith("bar")), |
| 71 endsWith("baz") | 71 endsWith("baz") |
| 72 ])); | 72 ])); |
| 73 }); | 73 }); |
| 74 } | 74 } |
| 75 ``` | 75 ``` |
| 76 | 76 |
| 77 ## Running Tests | 77 ## Running Tests |
| 78 | 78 |
| 79 A single test file can be run just using `dart path/to/test.dart`. | 79 A single test file can be run just using `dart path/to/test.dart`. |
| 80 | 80 |
| 81  | 81  |
| 82 | 82 |
| 83 Many tests can be run at a time using `pub run unittest:unittest path/to/dir`. | 83 Many tests can be run at a time using `pub run test:test path/to/dir`. |
| 84 | 84 |
| 85  | 85  |
| 86 | 86 |
| 87 `unittest` considers any file that ends with `_test.dart` to be a test file. If | 87 `test` considers any file that ends with `_test.dart` to be a test file. If |
| 88 you don't pass any paths, it will run all the test files in your `test/` | 88 you don't pass any paths, it will run all the test files in your `test/` |
| 89 directory, making it easy to test your entire application at once. | 89 directory, making it easy to test your entire application at once. |
| 90 | 90 |
| 91 By default, tests are run in the Dart VM, but you can run them in the browser as | 91 By default, tests are run in the Dart VM, but you can run them in the browser as |
| 92 well by passing `pub run unittest:unittest -p chrome path/to/test.dart`. | 92 well by passing `pub run test:test -p chrome path/to/test.dart`. |
| 93 `unittest` will take care of starting the browser and loading the tests, and all | 93 `test` will take care of starting the browser and loading the tests, and all |
| 94 the results will be reported on the command line just like for VM tests. In | 94 the results will be reported on the command line just like for VM tests. In |
| 95 fact, you can even run tests on both platforms with a single command: `pub run | 95 fact, you can even run tests on both platforms with a single command: `pub run |
| 96 unittest:unittest -p chrome -p vm path/to/test.dart`. | 96 test:test -p chrome -p vm path/to/test.dart`. |
| 97 | 97 |
| 98 ### Restricting Tests to Certain Platforms | 98 ### Restricting Tests to Certain Platforms |
| 99 | 99 |
| 100 Some test files only make sense to run on particular platforms. They may use | 100 Some test files only make sense to run on particular platforms. They may use |
| 101 `dart:html` or `dart:io`, they might test Windows' particular filesystem | 101 `dart:html` or `dart:io`, they might test Windows' particular filesystem |
| 102 behavior, or they might use a feature that's only available in Chrome. The | 102 behavior, or they might use a feature that's only available in Chrome. The |
| 103 [`@TestOn`][TestOn] annotation makes it easy to declare exactly which platforms | 103 [`@TestOn`][TestOn] annotation makes it easy to declare exactly which platforms |
| 104 a test file should run on. Just put it at the top of your file, before any | 104 a test file should run on. Just put it at the top of your file, before any |
| 105 `library` or `import` declarations: | 105 `library` or `import` declarations: |
| 106 | 106 |
| 107 ```dart | 107 ```dart |
| 108 @TestOn("vm") | 108 @TestOn("vm") |
| 109 | 109 |
| 110 import "dart:io"; | 110 import "dart:io"; |
| 111 | 111 |
| 112 import "package:unittest/unittest.dart"; | 112 import "package:test/test.dart"; |
| 113 | 113 |
| 114 void main() { | 114 void main() { |
| 115 // ... | 115 // ... |
| 116 } | 116 } |
| 117 ``` | 117 ``` |
| 118 | 118 |
| 119 [TestOn]: http://www.dartdocs.org/documentation/unittest/latest/index.html#unitt
est/unittest.TestOn | 119 [TestOn]: http://www.dartdocs.org/documentation/test/latest/index.html#test/test
.TestOn |
| 120 | 120 |
| 121 The string you pass to `@TestOn` is what's called a "platform selector", and it | 121 The string you pass to `@TestOn` is what's called a "platform selector", and it |
| 122 specifies exactly which platforms a test can run on. It can be as simple as the | 122 specifies exactly which platforms a test can run on. It can be as simple as the |
| 123 name of a platform, or a more complex Dart-like boolean expression involving | 123 name of a platform, or a more complex Dart-like boolean expression involving |
| 124 these platform names. | 124 these platform names. |
| 125 | 125 |
| 126 ### Platform Selector Syntax | 126 ### Platform Selector Syntax |
| 127 | 127 |
| 128 Platform selectors can contain identifiers, parentheses, and operators. When | 128 Platform selectors can contain identifiers, parentheses, and operators. When |
| 129 loading a test, each identifier is set to `true` or `false` based on the current | 129 loading a test, each identifier is set to `true` or `false` based on the current |
| (...skipping 37 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
| 167 write `@TestOn("browser && !chrome")`. | 167 write `@TestOn("browser && !chrome")`. |
| 168 | 168 |
| 169 ## Asynchronous Tests | 169 ## Asynchronous Tests |
| 170 | 170 |
| 171 Tests written with `async`/`await` will work automatically. The test runner | 171 Tests written with `async`/`await` will work automatically. The test runner |
| 172 won't consider the test finished until the returned `Future` completes. | 172 won't consider the test finished until the returned `Future` completes. |
| 173 | 173 |
| 174 ```dart | 174 ```dart |
| 175 import "dart:async"; | 175 import "dart:async"; |
| 176 | 176 |
| 177 import "package:unittest/unittest.dart"; | 177 import "package:test/test.dart"; |
| 178 | 178 |
| 179 void main() { | 179 void main() { |
| 180 test("new Future.value() returns the value", () async { | 180 test("new Future.value() returns the value", () async { |
| 181 var value = await new Future.value(10); | 181 var value = await new Future.value(10); |
| 182 expect(value, equals(10)); | 182 expect(value, equals(10)); |
| 183 }); | 183 }); |
| 184 } | 184 } |
| 185 ``` | 185 ``` |
| 186 | 186 |
| 187 There are also a number of useful functions and matchers for more advanced | 187 There are also a number of useful functions and matchers for more advanced |
| 188 asynchrony. The [`completion()`][completion] matcher can be used to test | 188 asynchrony. The [`completion()`][completion] matcher can be used to test |
| 189 `Futures`; it ensures that the test doesn't finish until the `Future` completes, | 189 `Futures`; it ensures that the test doesn't finish until the `Future` completes, |
| 190 and runs a matcher against that `Future`'s value. | 190 and runs a matcher against that `Future`'s value. |
| 191 | 191 |
| 192 [completion]: http://www.dartdocs.org/documentation/unittest/latest/index.html#u
nittest/unittest@id_completion | 192 [completion]: http://www.dartdocs.org/documentation/test/latest/index.html#test/
test@id_completion |
| 193 | 193 |
| 194 ```dart | 194 ```dart |
| 195 import "dart:async"; | 195 import "dart:async"; |
| 196 | 196 |
| 197 import "package:unittest/unittest.dart"; | 197 import "package:test/test.dart"; |
| 198 | 198 |
| 199 void main() { | 199 void main() { |
| 200 test("new Future.value() returns the value", () { | 200 test("new Future.value() returns the value", () { |
| 201 expect(new Future.value(10), completion(equals(10))); | 201 expect(new Future.value(10), completion(equals(10))); |
| 202 }); | 202 }); |
| 203 } | 203 } |
| 204 ``` | 204 ``` |
| 205 | 205 |
| 206 The [`throwsA()`][throwsA] matcher and the various `throwsExceptionType` | 206 The [`throwsA()`][throwsA] matcher and the various `throwsExceptionType` |
| 207 matchers work with both synchronous callbacks and asynchronous `Future`s. They | 207 matchers work with both synchronous callbacks and asynchronous `Future`s. They |
| 208 ensure that a particular type of exception is thrown: | 208 ensure that a particular type of exception is thrown: |
| 209 | 209 |
| 210 [completion]: http://www.dartdocs.org/documentation/unittest/latest/index.html#u
nittest/unittest@id_throwsA | 210 [completion]: http://www.dartdocs.org/documentation/test/latest/index.html#test/
test@id_throwsA |
| 211 | 211 |
| 212 ```dart | 212 ```dart |
| 213 import "dart:async"; | 213 import "dart:async"; |
| 214 | 214 |
| 215 import "package:unittest/unittest.dart"; | 215 import "package:test/test.dart"; |
| 216 | 216 |
| 217 void main() { | 217 void main() { |
| 218 test("new Future.error() throws the error", () { | 218 test("new Future.error() throws the error", () { |
| 219 expect(new Future.error("oh no"), throwsA(equals("oh no"))); | 219 expect(new Future.error("oh no"), throwsA(equals("oh no"))); |
| 220 expect(new Future.error(new StateError("bad state")), throwsStateError); | 220 expect(new Future.error(new StateError("bad state")), throwsStateError); |
| 221 }); | 221 }); |
| 222 } | 222 } |
| 223 ``` | 223 ``` |
| 224 | 224 |
| 225 The [`expectAsync()`][expectAsync] function wraps another function and has two | 225 The [`expectAsync()`][expectAsync] function wraps another function and has two |
| 226 jobs. First, it asserts that the wrapped function is called a certain number of | 226 jobs. First, it asserts that the wrapped function is called a certain number of |
| 227 times, and will cause the test to fail if it's called too often; second, it | 227 times, and will cause the test to fail if it's called too often; second, it |
| 228 keeps the test from finishing until the function is called the requisite number | 228 keeps the test from finishing until the function is called the requisite number |
| 229 of times. | 229 of times. |
| 230 | 230 |
| 231 ```dart | 231 ```dart |
| 232 import "dart:async"; | 232 import "dart:async"; |
| 233 | 233 |
| 234 import "package:unittest/unittest.dart"; | 234 import "package:test/test.dart"; |
| 235 | 235 |
| 236 void main() { | 236 void main() { |
| 237 test("Stream.fromIterable() emits the values in the iterable", () { | 237 test("Stream.fromIterable() emits the values in the iterable", () { |
| 238 var stream = new Stream.fromIterable([1, 2, 3]); | 238 var stream = new Stream.fromIterable([1, 2, 3]); |
| 239 | 239 |
| 240 stream.listen(expectAsync((number) { | 240 stream.listen(expectAsync((number) { |
| 241 expect(number, inInclusiveRange(1, 3)); | 241 expect(number, inInclusiveRange(1, 3)); |
| 242 }, count: 3)); | 242 }, count: 3)); |
| 243 }); | 243 }); |
| 244 } | 244 } |
| 245 ``` | 245 ``` |
| 246 | 246 |
| 247 [expectAsync]: http://www.dartdocs.org/documentation/unittest/latest/index.html#
unittest/unittest@id_expectAsync | 247 [expectAsync]: http://www.dartdocs.org/documentation/test/latest/index.html#test
/test@id_expectAsync |
| OLD | NEW |