Merge package:test_process

.github/ISSUE_TEMPLATE/test_process.md

@@ -0,0 +1,5 @@
+---
+name: "package:test_process"
+about: "Create a bug or file a feature request against package:test_process."
+labels: "package:test_process"
+---

.github/workflows/test_process.yaml

@@ -0,0 +1,72 @@
+name: package:test_process
+
+on:
+  # Run on PRs and pushes to the default branch.
+  push:
+    branches: [ master ]
+    paths:
+      - '.github/workflows/test_process.yaml'
+      - 'pkgs/test_process/**'
+  pull_request:
+    branches: [ master ]
+    paths:
+      - '.github/workflows/test_process.yaml'
+      - 'pkgs/test_process/**'
+  schedule:
+    - cron: "0 0 * * 0"
+
+env:
+  PUB_ENVIRONMENT: bot.github
+
+
+defaults:
+  run:
+    working-directory: pkgs/test_process/
+
+jobs:
+  # Check code formatting and static analysis on a single OS (linux)
+  # against Dart dev.
+  analyze:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        sdk: [dev]
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683
+      - uses: dart-lang/setup-dart@e630b99d28a3b71860378cafdc2a067c71107f94
+        with:
+          sdk: ${{ matrix.sdk }}
+      - id: install
+        name: Install dependencies
+        run: dart pub get
+      - name: Check formatting
+        run: dart format --output=none --set-exit-if-changed .
+        if: always() && steps.install.outcome == 'success'
+      - name: Analyze code
+        run: dart analyze --fatal-infos
+        if: always() && steps.install.outcome == 'success'
+
+  # Run tests on a matrix consisting of two dimensions:
+  # 1. OS: ubuntu-latest, (macos-latest, windows-latest)
+  # 2. release: dev
+  test:
+    needs: analyze
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        # Add macos-latest and/or windows-latest if relevant for this package.
+        os: [ubuntu-latest]
+        sdk: [3.1, dev]
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683
+      - uses: dart-lang/setup-dart@e630b99d28a3b71860378cafdc2a067c71107f94
+        with:
+          sdk: ${{ matrix.sdk }}
+      - id: install
+        name: Install dependencies
+        run: dart pub get
+      - name: Run VM tests
+        run: dart test --platform vm
+        if: always() && steps.install.outcome == 'success'

README.md

@@ -22,3 +22,4 @@ literate API.
 | [test](pkgs/test/) | A full featured library for writing and running Dart tests across platforms. | [![pub package](https://img.shields.io/pub/v/test.svg)](https://pub.dev/packages/test) |
 | [test_api](pkgs/test_api/) |  | [![pub package](https://img.shields.io/pub/v/test_api.svg)](https://pub.dev/packages/test_api) |
 | [test_core](pkgs/test_core/) |  | [![pub package](https://img.shields.io/pub/v/test_core.svg)](https://pub.dev/packages/test_core) |
+| [test_process](pkgs/test_process/) | Test processes: starting; validating stdout and stderr; checking exit code | [![pub package](https://img.shields.io/pub/v/test_process.svg)](https://pub.dev/packages/test_process) |

pkgs/test_process/.gitignore

@@ -0,0 +1,9 @@
+.buildlog
+.DS_Store
+.idea
+.settings/
+build/
+packages
+.packages
+pubspec.lock
+.dart_tool/

pkgs/test_process/AUTHORS

@@ -0,0 +1,6 @@
+# Below is a list of people and organizations that have contributed
+# to the project. Names should be added to the list like so:
+#
+#   Name/Organization <email address>
+
+Google Inc.

pkgs/test_process/CHANGELOG.md

@@ -0,0 +1,67 @@
+## 2.1.1
+
+* Require Dart 3.1.
+* Move to `dart-lang/test` monorepo.
+
+## 2.1.0
+
+- Remove the expectation that the process exits during the normal test body.
+  The process will still be killed during teardown if it has not exited. The
+  check can be manually restored with `shouldExit()`.
+
+## 2.0.3
+
+- Populate the pubspec `repository` field.
+- Fixed examples in `readme.md`.
+- Added `example/example.dart`
+- Require Dart >=2.17
+
+## 2.0.2
+
+- Reverted `meta` constraint to `^1.3.0`.
+
+## 2.0.1
+
+- Update `meta` constraint to `>=1.3.0 <3.0.0`.
+
+## 2.0.0
+
+- Migrate to null safety.
+
+## 1.0.6
+
+- Require Dart >=2.1
+
+## 1.0.5
+
+- Don't allow the test to time out as long as the process is emitting output.
+
+## 1.0.4
+
+- Set max SDK version to `<3.0.0`, and adjust other dependencies.
+
+## 1.0.3
+
+- Support test `1.x.x`.
+
+## 1.0.2
+
+- Update SDK version to 2.0.0-dev.17.0
+
+## 1.0.1
+
+- Declare support for `async` 2.0.0.
+
+## 1.0.0
+
+- Added `pid` and `exitCode` getters to `TestProcess`.
+
+## 1.0.0-rc.2
+
+- Subclassed `TestProcess`es now emit log output based on the superclass's
+  standard IO streams rather than the subclass's. This matches the documented
+  behavior.
+
+## 1.0.0-rc.1
+
+- Initial release candidate.

pkgs/test_process/LICENSE

@@ -0,0 +1,27 @@
+Copyright 2017, the Dart project authors.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are
+met:
+
+    * Redistributions of source code must retain the above copyright
+      notice, this list of conditions and the following disclaimer.
+    * Redistributions in binary form must reproduce the above
+      copyright notice, this list of conditions and the following
+      disclaimer in the documentation and/or other materials provided
+      with the distribution.
+    * Neither the name of Google LLC nor the names of its
+      contributors may be used to endorse or promote products derived
+      from this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

pkgs/test_process/README.md

@@ -0,0 +1,123 @@
+[![Build Status](https://github.com/dart-lang/test/actions/workflows/test_process.yaml/badge.svg)](https://github.com/dart-lang/test/actions/workflows/test_process.yaml)
+[![pub package](https://img.shields.io/pub/v/test_process.svg)](https://pub.dev/packages/test_process)
+[![package publisher](https://img.shields.io/pub/publisher/test_process.svg)](https://pub.dev/packages/test_process/publisher)
+
+A package for testing subprocesses.
+
+This exposes a [`TestProcess`][TestProcess] class that wraps `dart:io`'s
+[`Process`][Process] class and makes it easy to read standard output
+line-by-line. `TestProcess` works the same as `Process` in many ways, but there
+are a few major differences.
+
+[TestProcess]: https://pub.dev/documentation/test_process/latest/test_process/TestProcess-class.html
+[Process]: https://api.dart.dev/stable/dart-io/Process-class.html
+
+## Standard Output
+
+`Process.stdout` and `Process.stderr` are binary streams, which is the most
+general API but isn't the most helpful when working with a program that produces
+plain text. Instead, [`TestProcess.stdout`][stdout] and
+[`TestProcess.stderr`][stderr] emit a string for each line of output the process
+produces. What's more, they're [`StreamQueue`][StreamQueue]s, which means
+they provide a *pull-based API*. For example:
+
+[stdout]: https://pub.dev/documentation/test_process/latest/test_process/TestProcess/stdout.html
+[stderr]: https://pub.dev/documentation/test_process/latest/test_process/TestProcess/stderr.html
+[StreamQueue]: https://pub.dev/documentation/async/latest/async/StreamQueue-class.html
+
+```dart
+import 'package:test/test.dart';
+import 'package:test_process/test_process.dart';
+
+void main() {
+  test('pub get gets dependencies', () async {
+    // TestProcess.start() works just like Process.start() from dart:io.
+    var process = await TestProcess.start('dart', ['pub', 'get']);
+
+    // StreamQueue.next returns the next line emitted on standard out.
+    var firstLine = await process.stdout.next;
+    expect(firstLine, equals('Resolving dependencies...'));
+
+    // Each call to StreamQueue.next moves one line further.
+    String next;
+    do {
+      next = await process.stdout.next;
+    } while (next != 'Got dependencies!');
+
+    // Assert that the process exits with code 0.
+    await process.shouldExit(0);
+  });
+}
+```
+
+The `test` package's [stream matchers][] have built-in support for
+`StreamQueues`, which makes them perfect for making assertions about a process's
+output. We can use this to clean up the previous example:
+
+[stream matchers]: https://github.com/dart-lang/test#stream-matchers
+
+```dart
+import 'package:test/test.dart';
+import 'package:test_process/test_process.dart';
+
+void main() {
+  test('pub get gets dependencies', () async {
+    var process = await TestProcess.start('dart', ['pub', 'get']);
+
+    // Each stream matcher will consume as many lines as it matches from a
+    // StreamQueue, and no more, so it's safe to use them in sequence.
+    await expectLater(process.stdout, emits('Resolving dependencies...'));
+
+    // The emitsThrough matcher matches and consumes any number of lines, as
+    // long as they end with one matching the argument.
+    await expectLater(process.stdout, emitsThrough('Got dependencies!'));
+
+    await process.shouldExit(0);
+  });
+}
+```
+
+If you want to access the standard output streams without consuming any values
+from the queues, you can use the [`stdoutStream()`][stdoutStream] and
+[`stderrStream()`][stderrStream] methods. Each time you call one of these, it
+produces an entirely new stream that replays the corresponding output stream
+from the beginning, regardless of what's already been produced by `stdout`,
+`stderr`, or other calls to the stream method.
+
+[stdoutStream]: https://pub.dev/documentation/test_process/latest/test_process/TestProcess/stdoutStream.html
+[stderrStream]: https://pub.dev/documentation/test_process/latest/test_process/TestProcess/stderrStream.html
+
+## Signals and Termination
+
+The way signaling works is different from `dart:io` as well. `TestProcess` still
+has a [`kill()`][kill] method, but it defaults to `SIGKILL` on Mac OS and Linux
+to ensure (as best as possible) that processes die without leaving behind
+zombies. If you want to send a particular signal (which is unsupported on
+Windows), you can do so by explicitly calling [`signal()`][signal].
+
+[kill]: https://pub.dev/documentation/test_process/latest/test_process/TestProcess/kill.html
+[signal]: https://pub.dev/documentation/test_process/latest/test_process/TestProcess/signal.html
+
+In addition to [`exitCode`][exitCode], which works the same as in `dart:io`,
+`TestProcess` also adds a new method named [`shouldExit()`][shouldExit]. This
+lets tests wait for a process to exit, and (if desired) assert what particular
+exit code it produced.
+
+[exitCode]: https://pub.dev/documentation/test_process/latest/test_process/TestProcess/exitCode.html
+[shouldExit]: https://pub.dev/documentation/test_process/latest/test_process/TestProcess/shouldExit.html
+
+## Debugging Output
+
+When a test using `TestProcess` fails, it will print all the output produced by
+that process. This makes it much easier to figure out what went wrong and why.
+The debugging output uses a header based on the process's invocation by
+default, but you can pass in custom `description` parameters to
+[`TestProcess.start()`][start] to control the headers.
+
+[start]: https://pub.dev/documentation/test_process/latest/test_process/TestProcess/start.html
+
+`TestProcess` will also produce debugging output as the test runs if you pass
+`forwardStdio: true` to `TestProcess.start()`. This can be particularly useful
+when you're using an interactive debugger and you want to figure out what a
+process is doing before the test finishes and the normal debugging output is
+printed.

pkgs/test_process/analysis_options.yaml

@@ -0,0 +1,18 @@
+# https://dart.dev/tools/analysis#the-analysis-options-file
+include: package:dart_flutter_team_lints/analysis_options.yaml
+
+analyzer:
+  language:
+    strict-casts: true
+    strict-inference: true
+    strict-raw-types: true
+
+linter:
+  rules:
+    - avoid_unused_constructor_parameters
+    - cancel_subscriptions
+    - literal_only_boolean_expressions
+    - missing_whitespace_between_adjacent_strings
+    - no_adjacent_strings_in_list
+    - no_runtimeType_toString
+    - unnecessary_await_in_return

pkgs/test_process/example/example.dart

@@ -0,0 +1,26 @@
+// Copyright (c) 2022, the Dart project authors.  Please see the AUTHORS file
+// for details. All rights reserved. Use of this source code is governed by a
+// BSD-style license that can be found in the LICENSE file.
+
+import 'package:test/test.dart';
+import 'package:test_process/test_process.dart';
+
+void main() {
+  test('pub get gets dependencies', () async {
+    // TestProcess.start() works just like Process.start() from dart:io.
+    var process = await TestProcess.start('dart', ['pub', 'get']);
+
+    // StreamQueue.next returns the next line emitted on standard out.
+    var firstLine = await process.stdout.next;
+    expect(firstLine, equals('Resolving dependencies...'));
+
+    // Each call to StreamQueue.next moves one line further.
+    String next;
+    do {
+      next = await process.stdout.next;
+    } while (next != 'Got dependencies!');
+
+    // Assert that the process exits with code 0.
+    await process.shouldExit(0);
+  });
+}