Merge package:test_descriptor

.github/ISSUE_TEMPLATE/test_descriptor.md

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

.github/workflows/test_descriptor.yaml

@@ -0,0 +1,72 @@
+name: package:test_descriptor
+
+on:
+  # Run on PRs and pushes to the default branch.
+  push:
+    branches: [ master ]
+    paths:
+      - '.github/workflows/test_descriptor.yaml'
+      - 'pkgs/test_descriptor/**'
+  pull_request:
+    branches: [ master ]
+    paths:
+      - '.github/workflows/test_descriptor.yaml'
+      - 'pkgs/test_descriptor/**'
+  schedule:
+    - cron: "0 0 * * 0"
+
+env:
+  PUB_ENVIRONMENT: bot.github
+
+
+defaults:
+  run:
+    working-directory: pkgs/test_descriptor/
+
+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 channel: 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,4 +22,5 @@ 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_descriptor](pkgs/test_descriptor/) | An API for defining and verifying files and directory structures. | [![pub package](https://img.shields.io/pub/v/test_descriptor.svg)](https://pub.dev/packages/test_descriptor) |
 | [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_descriptor/.gitignore

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

pkgs/test_descriptor/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_descriptor/CHANGELOG.md

@@ -0,0 +1,59 @@
+## 2.0.2
+
+* Require Dart 3.1 or later.
+* Move to `dart-lang/test` monorepo.
+
+## 2.0.1
+
+* Populate the pubspec `repository` field.
+* Migrate to `package:lints`.
+* Update the package's markdown badges.
+
+## 2.0.0
+
+* Null safety stable release.
+* BREAKING: Removed archive support.
+* BREAKING: `DirectoryDescriptor.load` only supports a `String` path instead of
+  also accepting relative `Uri` objects.
+* BREAKING: `DirectoryDescriptor.load` no longer has an optional `parents`
+  parameter - this was intended for internal use only.
+
+## 1.2.0
+
+* Add an `ArchiveDescriptor` class and a corresponding `archive()` function that
+  can create and validate Zip and TAR archives.
+
+## 1.1.1
+
+* Update to lowercase Dart core library constants.
+
+## 1.1.0
+
+* Add a `path()` function that returns the a path within the sandbox directory.
+
+* Add `io` getters to `FileDescriptor` and `DirectoryDescriptor` that returns
+  `dart:io` `File` and `Directory` objects, respectively, within the sandbox
+  directory.
+
+## 1.0.4
+
+* Support test `1.x.x'.
+
+## 1.0.3
+
+* Stop using comment-based generics.
+
+## 1.0.2
+
+* Declare support for `async` 2.0.0.
+
+## 1.0.1
+
+* `FileDescriptor.validate()` now allows invalid UTF-8 files.
+
+* Fix a bug where `DirectoryDescriptor.load()` would incorrectly report that
+  multiple versions of a file or directory existed.
+
+## 1.0.0
+
+* Initial version.

pkgs/test_descriptor/LICENSE

@@ -0,0 +1,27 @@
+Copyright 2016, 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_descriptor/README.md

@@ -0,0 +1,56 @@
+[![Build Status](https://github.com/dart-lang/test/actions/workflows/test_descriptor.yaml/badge.svg)](https://github.com/dart-lang/test/actions/workflows/test_descriptor.yaml)
+[![pub package](https://img.shields.io/pub/v/test_descriptor.svg)](https://pub.dev/packages/test_descriptor)
+[![package publisher](https://img.shields.io/pub/publisher/test_descriptor.svg)](https://pub.dev/packages/test_descriptor/publisher)
+
+The `test_descriptor` package provides a convenient, easy-to-read API for
+defining and verifying directory structures in tests.
+
+## Usage
+
+We recommend that you import this library with the `d` prefix. The
+[`d.dir()`][dir] and [`d.file()`][file] functions are the main entrypoints. They
+define a filesystem structure that can be created using
+[`Descriptor.create()`][create] and verified using
+[`Descriptor.validate()`][validate]. For example:
+
+[dir]: https://pub.dev/documentation/test_descriptor/latest/test_descriptor/dir.html
+[file]: https://pub.dev/documentation/test_descriptor/latest/test_descriptor/file.html
+[create]: https://pub.dev/documentation/test_descriptor/latest/test_descriptor/Descriptor/create.html
+[validate]: https://pub.dev/documentation/test_descriptor/latest/test_descriptor/Descriptor/validate.html
+
+```dart
+import 'dart:io';
+
+import 'package:test/test.dart';
+import 'package:test_descriptor/test_descriptor.dart' as d;
+
+void main() {
+  test('Directory.rename', () async {
+    await d.dir('parent', [
+      d.file('sibling', 'sibling-contents'),
+      d.dir('old-name', [d.file('child', 'child-contents')])
+    ]).create();
+
+    await Directory('${d.sandbox}/parent/old-name')
+        .rename('${d.sandbox}/parent/new-name');
+
+    await d.dir('parent', [
+      d.file('sibling', 'sibling-contents'),
+      d.dir('new-name', [d.file('child', 'child-contents')])
+    ]).validate();
+  });
+}
+```
+
+By default, descriptors create entries in a temporary sandbox directory,
+[`d.sandbox`][sandbox]. A new sandbox is automatically created the first time
+you create a descriptor in a given test, and automatically deleted once the test
+finishes running.
+
+[sandbox]: https://pub.dev/documentation/test_descriptor/latest/test_descriptor/sandbox.html
+
+This package is [`term_glyph`][term_glyph] aware. It will decide whether to use
+ASCII or Unicode glyphs based on the [`glyph.ascii`][ascii] attribute.
+
+[term_glyph]: https://pub.dev/packages/term_glyph
+[ascii]: https://pub.dev/documentation/term_glyph/latest/term_glyph/ascii.html

pkgs/test_descriptor/analysis_options.yaml

@@ -0,0 +1,33 @@
+# https://dart.dev/guides/language/analysis-options
+include: package:dart_flutter_team_lints/analysis_options.yaml
+
+analyzer:
+  language:
+    strict-casts: true
+    strict-inference: true
+    strict-raw-types: true
+
+linter:
+  rules:
+    - avoid_bool_literals_in_conditional_expressions
+    - avoid_classes_with_only_static_members
+    - avoid_private_typedef_functions
+    - avoid_redundant_argument_values
+    - avoid_returning_this
+    - avoid_unused_constructor_parameters
+    - avoid_void_async
+    - cancel_subscriptions
+    - join_return_with_assignment
+    - literal_only_boolean_expressions
+    - missing_whitespace_between_adjacent_strings
+    - no_adjacent_strings_in_list
+    - no_runtimeType_toString
+    - prefer_const_declarations
+    - prefer_expression_function_bodies
+    - prefer_final_locals
+    - unnecessary_await_in_return
+    - unnecessary_raw_strings
+    - use_if_null_to_convert_nulls_to_bools
+    - use_raw_strings
+    - use_string_buffers
+    - require_trailing_commas

pkgs/test_descriptor/example/example.dart

@@ -0,0 +1,25 @@
+// 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 'dart:io';
+
+import 'package:test/test.dart';
+import 'package:test_descriptor/test_descriptor.dart' as d;
+
+void main() {
+  test('Directory.rename', () async {
+    await d.dir('parent', [
+      d.file('sibling', 'sibling-contents'),
+      d.dir('old-name', [d.file('child', 'child-contents')]),
+    ]).create();
+
+    await Directory('${d.sandbox}/parent/old-name')
+        .rename('${d.sandbox}/parent/new-name');
+
+    await d.dir('parent', [
+      d.file('sibling', 'sibling-contents'),
+      d.dir('new-name', [d.file('child', 'child-contents')]),
+    ]).validate();
+  });
+}

pkgs/test_descriptor/lib/src/descriptor.dart

@@ -0,0 +1,26 @@
+// Copyright (c) 2017, 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 'sandbox.dart';
+
+/// A declarative description of a filesystem entry.
+///
+/// This may be extended outside this package.
+abstract class Descriptor {
+  /// This entry's basename.
+  final String name;
+
+  Descriptor(this.name);
+
+  /// Creates this entry within the [parent] directory, which defaults to
+  /// [sandbox].
+  Future<void> create([String? parent]);
+
+  /// Validates that the physical file system under [parent] (which defaults to
+  /// [sandbox]) contains an entry that matches this descriptor.
+  Future<void> validate([String? parent]);
+
+  /// Returns a human-friendly tree-style description of this descriptor.
+  String describe();
+}