Skip to content

Commit d5eedec

Browse files
matanlureymatanlurey
authored
Add documentation/improve README. (#302)
1 parent e7c25e7 commit d5eedec

File tree

9 files changed

+110
-8
lines changed

9 files changed

+110
-8
lines changed

‎build_test/README.md‎

Lines changed: 87 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,88 @@
1-
This library provides some utilities for unit testing `Builder`s.
1+
# build_test
22

3-
See the `test` folder in the `build` package for examples.
3+
Testing utilities for users of [`package:build`][].
4+
5+
<p align="center">
6+
<a href="https://travis-ci.org/dart-lang/build">
7+
<img src="https://travis-ci.org/dart-lang/build.svg?branch=master" alt="Build Status" />
8+
</a>
9+
<a href="https://github.com/dart-lang/build/labels/package%3Abuild_test">
10+
<img src="https://img.shields.io/github/issues-raw/dart-lang/build/package%3Abuild_test.svg" alt="Issues related to build_test" />
11+
</a>
12+
<a href="https://pub.dartlang.org/packages/build_test">
13+
<img src="https://img.shields.io/pub/v/build_test.svg" alt="Pub Package Version" />
14+
</a>
15+
<a href="https://www.dartdocs.org/documentation/build_test/latest">
16+
<img src="https://img.shields.io/badge/dartdocs-latest-blue.svg" alt="Latest Dartdocs" />
17+
</a>
18+
<a href="https://gitter.im/dart-lang/source_gen">
19+
<img src="https://badges.gitter.im/dart-lang/source_gen.svg" alt="Join the chat on Gitter" />
20+
</a>
21+
</p>
22+
23+
## Installation
24+
25+
This package is intended to only be as a [development dependency][] for users
26+
of [`package:build`][], and should not be used in any production code. Simply
27+
add to your `pubspec.yaml`:
28+
29+
```yaml
30+
dev_dependencies:
31+
build_test:
32+
```
33+
34+
## Usage
35+
36+
_See the `test` folder in the `build` package for more examples_.
37+
38+
### Resolve source code for testing
39+
40+
Using [`resolveAsset`][api:resolveAsset] and
41+
[`resolveSource`][api:resolveSource], you can resolve Dart source code into a
42+
static element model, suitable for probing and using within tests of code you
43+
might have written for a `Builder`:
44+
45+
```dart
46+
test('should resolve a simple dart file', () async {
47+
var resolver = await resolveSource(r'''
48+
library example;
49+
50+
class Foo {}
51+
''');
52+
var libExample = resolver.getLibraryByName('example');
53+
expect(libExample.getType('Foo'), isNotNull);
54+
});
55+
```
56+
57+
### Run a `Builder` within a test environment
58+
59+
Using [`testBuilder`][api:testBuilder], you can run a functional test of a
60+
`Builder`, including feeding specific assets, and more. It automatically
61+
creates an in-memory representation of various utility classes.
62+
63+
### Various test implementations of classes
64+
65+
* [`FakeWatcher`][api:FakeWatcher]
66+
* [`InMemoryAssetReader`][api:InMemoryAssetReader]
67+
* [`InMemoryAssetWriter`][api:InMemoryAssetWriter]
68+
* [`MultiAssetReader`][api:MultiAssetReader]
69+
* [`PackageAssetReader`][api:PackageAssetReader]
70+
* [`RecordingAssetWriter`][api:RecordingAssetWriter]
71+
* [`StubAssetReader`][api:StubAssetReader]
72+
* [`StubAssetWriter`][api:StubAssetWriter]
73+
74+
[development dependency]: https://www.dartlang.org/tools/pub/dependencies#dev-dependencies
75+
[`package:build`]: https://pub.dartlang.org/packages/build
76+
77+
[api:FakeWatcher]: https://www.dartdocs.org/documentation/build_test/latest/build_test/FakeWatcher-class.html
78+
[api:InMemoryAssetReader]: https://www.dartdocs.org/documentation/build_test/latest/build_test/InMemoryAssetReader-class.html
79+
[api:InMemoryAssetWriter]: https://www.dartdocs.org/documentation/build_test/latest/build_test/InMemoryAssetWriter-class.html
80+
[api:MultiAssetReader]: https://www.dartdocs.org/documentation/build_test/latest/build_test/MultiAssetReader-class.html
81+
[api:PackageAssetReader]: https://www.dartdocs.org/documentation/build_test/latest/build_test/PackageAssetReader-class.html
82+
[api:RecordingAssetWriter]: https://www.dartdocs.org/documentation/build_test/latest/build_test/RecordingAssetWriter-class.html
83+
[api:StubAssetReader]: https://www.dartdocs.org/documentation/build_test/latest/build_test/StubAssetReader-class.html
84+
[api:StubAssetWriter]: https://www.dartdocs.org/documentation/build_test/latest/build_test/StubAssetWriter-class.html
85+
86+
[api:resolveAsset]: https://www.dartdocs.org/documentation/build_test/latest/build_test/resolveAsset.html
87+
[api:resolveSource]: https://www.dartdocs.org/documentation/build_test/latest/build_test/resolveSource.html
88+
[api:testBuilder]: https://www.dartdocs.org/documentation/build_test/latest/build_test/testBuilder.html

‎build_test/lib/src/fake_watcher.dart‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@ import 'package:watcher/watcher.dart';
77

88
/// A fake [DirectoryWatcher].
99
///
10-
/// Use the static [FakeWatcher#notifyPath] method to add events.
10+
/// Use the static [notifyWatchers] method to add simulated events.
1111
class FakeWatcher implements DirectoryWatcher {
1212
@override
1313
String get directory => path;

‎build_test/lib/src/in_memory_reader.dart‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,10 +9,14 @@ import 'package:glob/glob.dart';
99

1010
import 'in_memory_writer.dart';
1111

12+
/// An implementation of [AssetReader] with primed in-memory assets.
1213
class InMemoryAssetReader implements AssetReader {
1314
final Map<AssetId, DatedValue> assets;
1415
final String rootPackage;
1516

17+
/// Create a new asset reader that contains [sourceAssets].
18+
///
19+
/// May optionally define a [rootPackage], which is required for some APIs.
1620
InMemoryAssetReader({Map<AssetId, DatedValue> sourceAssets, this.rootPackage})
1721
: assets = sourceAssets ?? <AssetId, DatedValue>{};
1822

‎build_test/lib/src/in_memory_writer.dart‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,10 +6,12 @@ import 'dart:convert';
66

77
import 'package:build/build.dart';
88

9+
/// An implementation of [AssetWriter] that records outputs to [assets].
910
abstract class RecordingAssetWriter implements AssetWriter {
1011
Map<AssetId, DatedValue> get assets;
1112
}
1213

14+
/// An implementation of [AssetWriter] that writes outputs to memory.
1315
class InMemoryAssetWriter implements RecordingAssetWriter {
1416
@override
1517
final Map<AssetId, DatedValue> assets = {};

‎build_test/lib/src/multi_asset_reader.dart‎

Lines changed: 0 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -13,10 +13,6 @@ import 'package:glob/glob.dart';
1313
///
1414
/// [MultiAssetReader] attempts to check every provided [AssetReader] to see if
1515
/// they are capable of reading an [AssetId], otherwise checks the next reader.
16-
///
17-
/// **INTERNAL ONLY**: Only used as part of `build_test` for now for allowing a
18-
/// combination of "fake" assets (in-memory provided by a test) and "real"
19-
/// assets (i.e. dependencies we want resolved).
2016
class MultiAssetReader implements AssetReader {
2117
final List<AssetReader> _readers;
2218

‎build_test/lib/src/package_reader.dart‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,13 @@ import 'package:package_resolver/package_resolver.dart';
1212
import 'package:path/path.dart' as p;
1313

1414
/// Resolves using a [SyncPackageResolver] before reading from the file system.
15+
///
16+
/// For a simple implementation that uses the current isolate's package
17+
/// resolution logic (i.e. whatever you have generated in `.packages` in most
18+
/// cases), use [currentIsolate]:
19+
/// ```dart
20+
/// var assetReader = await PackageAssetReader.currentIsolate();
21+
/// ```
1522
class PackageAssetReader implements AssetReader {
1623
final SyncPackageResolver _packageResolver;
1724

@@ -27,6 +34,8 @@ class PackageAssetReader implements AssetReader {
2734
const PackageAssetReader(this._packageResolver, [this._rootPackage]);
2835

2936
/// A reader that can resolve files known to the current isolate.
37+
///
38+
/// A [rootPackage] should be provided for full API compatibility.
3039
static Future<PackageAssetReader> currentIsolate({String rootPackage}) async {
3140
var resolver = PackageResolver.current;
3241
return new PackageAssetReader(await resolver.asSync, rootPackage);

‎build_test/lib/src/stub_reader.dart‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,10 @@ import 'dart:convert';
77
import 'package:build/build.dart';
88
import 'package:glob/glob.dart';
99

10+
/// A no-op implementation of [AssetReader].
1011
class StubAssetReader implements AssetReader {
12+
const StubAssetReader();
13+
1114
@override
1215
FutureOr<bool> canRead(_) => null;
1316

‎build_test/lib/src/stub_writer.dart‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,10 @@ import 'dart:convert';
66

77
import 'package:build/build.dart';
88

9+
/// A no-op implementation of [AssetWriter].
910
class StubAssetWriter implements AssetWriter {
11+
const StubAssetWriter();
12+
1013
@override
1114
Future writeAsBytes(_, __) => new Future.value(null);
1215

‎build_test/pubspec.yaml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
name: build_test
2-
description: Utilities for writing unit tests of Builders.
2+
description: Testing utilities for users of package:build.
33
version: 0.6.2
44
author: Dart Team <[email protected]>
55
homepage: https://github.com/dart-lang/build

0 commit comments

Comments
 (0)