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 |