|
| 1 | +[](https://github.com/dart-lang/test_process/actions/workflows/test-package.yml) |
| 2 | +[](https://pub.dev/packages/test_process) |
| 3 | +[](https://pub.dev/packages/test_process/publisher) |
| 4 | + |
| 5 | +A package for testing subprocesses. |
| 6 | + |
| 7 | +This exposes a [`TestProcess`][TestProcess] class that wraps `dart:io`'s |
| 8 | +[`Process`][Process] class and makes it easy to read standard output |
| 9 | +line-by-line. `TestProcess` works the same as `Process` in many ways, but there |
| 10 | +are a few major differences. |
| 11 | + |
| 12 | +[TestProcess]: https://pub.dev/documentation/test_process/latest/test_process/TestProcess-class.html |
| 13 | +[Process]: https://api.dart.dev/stable/dart-io/Process-class.html |
| 14 | + |
| 15 | +## Standard Output |
| 16 | + |
| 17 | +`Process.stdout` and `Process.stderr` are binary streams, which is the most |
| 18 | +general API but isn't the most helpful when working with a program that produces |
| 19 | +plain text. Instead, [`TestProcess.stdout`][stdout] and |
| 20 | +[`TestProcess.stderr`][stderr] emit a string for each line of output the process |
| 21 | +produces. What's more, they're [`StreamQueue`][StreamQueue]s, which means |
| 22 | +they provide a *pull-based API*. For example: |
| 23 | + |
| 24 | +[stdout]: https://pub.dev/documentation/test_process/latest/test_process/TestProcess/stdout.html |
| 25 | +[stderr]: https://pub.dev/documentation/test_process/latest/test_process/TestProcess/stderr.html |
| 26 | +[StreamQueue]: https://pub.dev/documentation/async/latest/async/StreamQueue-class.html |
| 27 | + |
| 28 | +```dart |
| 29 | +import 'package:test/test.dart'; |
| 30 | +import 'package:test_process/test_process.dart'; |
| 31 | +
|
| 32 | +void main() { |
| 33 | + test('pub get gets dependencies', () async { |
| 34 | + // TestProcess.start() works just like Process.start() from dart:io. |
| 35 | + var process = await TestProcess.start('dart', ['pub', 'get']); |
| 36 | +
|
| 37 | + // StreamQueue.next returns the next line emitted on standard out. |
| 38 | + var firstLine = await process.stdout.next; |
| 39 | + expect(firstLine, equals('Resolving dependencies...')); |
| 40 | +
|
| 41 | + // Each call to StreamQueue.next moves one line further. |
| 42 | + String next; |
| 43 | + do { |
| 44 | + next = await process.stdout.next; |
| 45 | + } while (next != 'Got dependencies!'); |
| 46 | +
|
| 47 | + // Assert that the process exits with code 0. |
| 48 | + await process.shouldExit(0); |
| 49 | + }); |
| 50 | +} |
| 51 | +``` |
| 52 | + |
| 53 | +The `test` package's [stream matchers][] have built-in support for |
| 54 | +`StreamQueues`, which makes them perfect for making assertions about a process's |
| 55 | +output. We can use this to clean up the previous example: |
| 56 | + |
| 57 | +[stream matchers]: https://github.com/dart-lang/test#stream-matchers |
| 58 | + |
| 59 | +```dart |
| 60 | +import 'package:test/test.dart'; |
| 61 | +import 'package:test_process/test_process.dart'; |
| 62 | +
|
| 63 | +void main() { |
| 64 | + test('pub get gets dependencies', () async { |
| 65 | + var process = await TestProcess.start('dart', ['pub', 'get']); |
| 66 | +
|
| 67 | + // Each stream matcher will consume as many lines as it matches from a |
| 68 | + // StreamQueue, and no more, so it's safe to use them in sequence. |
| 69 | + await expectLater(process.stdout, emits('Resolving dependencies...')); |
| 70 | +
|
| 71 | + // The emitsThrough matcher matches and consumes any number of lines, as |
| 72 | + // long as they end with one matching the argument. |
| 73 | + await expectLater(process.stdout, emitsThrough('Got dependencies!')); |
| 74 | +
|
| 75 | + await process.shouldExit(0); |
| 76 | + }); |
| 77 | +} |
| 78 | +``` |
| 79 | + |
| 80 | +If you want to access the standard output streams without consuming any values |
| 81 | +from the queues, you can use the [`stdoutStream()`][stdoutStream] and |
| 82 | +[`stderrStream()`][stderrStream] methods. Each time you call one of these, it |
| 83 | +produces an entirely new stream that replays the corresponding output stream |
| 84 | +from the beginning, regardless of what's already been produced by `stdout`, |
| 85 | +`stderr`, or other calls to the stream method. |
| 86 | + |
| 87 | +[stdoutStream]: https://pub.dev/documentation/test_process/latest/test_process/TestProcess/stdoutStream.html |
| 88 | +[stderrStream]: https://pub.dev/documentation/test_process/latest/test_process/TestProcess/stderrStream.html |
| 89 | + |
| 90 | +## Signals and Termination |
| 91 | + |
| 92 | +The way signaling works is different from `dart:io` as well. `TestProcess` still |
| 93 | +has a [`kill()`][kill] method, but it defaults to `SIGKILL` on Mac OS and Linux |
| 94 | +to ensure (as best as possible) that processes die without leaving behind |
| 95 | +zombies. If you want to send a particular signal (which is unsupported on |
| 96 | +Windows), you can do so by explicitly calling [`signal()`][signal]. |
| 97 | + |
| 98 | +[kill]: https://pub.dev/documentation/test_process/latest/test_process/TestProcess/kill.html |
| 99 | +[signal]: https://pub.dev/documentation/test_process/latest/test_process/TestProcess/signal.html |
| 100 | + |
| 101 | +In addition to [`exitCode`][exitCode], which works the same as in `dart:io`, |
| 102 | +`TestProcess` also adds a new method named [`shouldExit()`][shouldExit]. This |
| 103 | +lets tests wait for a process to exit, and (if desired) assert what particular |
| 104 | +exit code it produced. |
| 105 | + |
| 106 | +[exitCode]: https://pub.dev/documentation/test_process/latest/test_process/TestProcess/exitCode.html |
| 107 | +[shouldExit]: https://pub.dev/documentation/test_process/latest/test_process/TestProcess/shouldExit.html |
| 108 | + |
| 109 | +## Debugging Output |
| 110 | + |
| 111 | +When a test using `TestProcess` fails, it will print all the output produced by |
| 112 | +that process. This makes it much easier to figure out what went wrong and why. |
| 113 | +The debugging output uses a header based on the process's invocation by |
| 114 | +default, but you can pass in custom `description` parameters to |
| 115 | +[`TestProcess.start()`][start] to control the headers. |
| 116 | + |
| 117 | +[start]: https://pub.dev/documentation/test_process/latest/test_process/TestProcess/start.html |
| 118 | + |
| 119 | +`TestProcess` will also produce debugging output as the test runs if you pass |
| 120 | +`forwardStdio: true` to `TestProcess.start()`. This can be particularly useful |
| 121 | +when you're using an interactive debugger and you want to figure out what a |
| 122 | +process is doing before the test finishes and the normal debugging output is |
| 123 | +printed. |
0 commit comments