Merge pull request #9 from Workiva/health_and_maintenance

CPLAT-7724 Address health and maintenance suggestions from pub.dev

CHANGELOG.md

@@ -1,3 +1,14 @@
+## 1.0.2
+
+- Fix #8.
+
+- Address pub health/maintenance recommendations (add an example, add missing
+  doc comments).
+
+## 1.0.1
+
+- Update package metadata in `pubspec.yaml`.
+
 ## 1.0.0
 
 - Initial version.

CONTRIBUTING.md

@@ -0,0 +1,16 @@
+# Contributing
+
+- `dartanalyzer .`
+- `dartfmt -w .`
+- `pub run test`
+
+If you make changes to `lib/src/config.dart` and need to regenerate
+`lib/src/config.g.dart`:
+
+1. Uncomment the `json_serializable: ^3.0.0` dev dependency in `pubspec.yaml`
+1. Comment out the entirety of `build.yaml`
+1. `pub get && pub run build_runner build`
+
+This is necessary because a builder cannot depend on code that is generated by
+another builder in the same package. An alternative solution would be to define
+the `TestHtmlBuilderConfig` in a separate package, but this is simpler for now.

README.md

@@ -23,13 +23,12 @@ Create as many HTML test templates in the `test/` directory as needed, e.g.:
         <!-- Load custom assets needed by the test. -->
         <script src="custom.js"></script>
 
-        <!--
-        Every template must include this `{test}` token.
-        It will be replaced by the builder with the required tags:
+        <!-- Every template must include this token. -->
+        {test}
+        <!-- It will be replaced by the builder with the required tags:
         <link rel="x-dart-test" href="...">
         <script src="packages/test/dart.js"></script>
         -->
-        {test}
     </head>
 </html>
 ```
@@ -43,39 +42,44 @@ targets:
       test_html_builder:
         options:
           templates:
+            "test/react_with_styles_template.html":
+              - "test/components/styled/**_test.dart"
             "test/react_template.html":
               - "test/components/**_test.dart"
-              - "test/react/**_test.dart"
-            "test/default_template.html":
-              - "test/**_test.dart"
 ```
 
-Notes:
+To illustrate how this works, consider an example test directory structure:
+
+- `test/`
+  - `foo_test.dart`
+  - `react_template.html`
+  - `react_with_styles_template.html`
+  - `components/`
+    - `bar_test.dart`
+    - `styled/`
+      - `baz_test.dart`
+
+Running tests via `pub run build_runner test` with the above configuration will
+result in the following (hidden) generated outputs:
 
-* If there is overlap between the globs defined for multiple templates, the
+- `test/components/bar_test.html` (from `react_template.html`)
+- `test/components/styled/baz_test.html` (from `react_with_styles_template.html`)
+
+### Notes
+
+- If there is overlap between the globs defined for multiple templates, the
   builder will choose the first template that matches.
 
-* If none of the templates match for a given test file, no html file will be
+- If none of the templates match for a given test file, no html file will be
   generated.
 
-* One-off custom html files for individual tests are still supported, but they
+- One-off custom html files for individual tests are still supported, but they
   must use the `.custom.html` extension:
-  * test/example_test.dart
-  * test/example_test.custom.html
+  - `test/example_test.dart`
+  - `test/example_test.custom.html`
 
 ## Contributing
 
-* `dartanalyzer .`
-* `dartfmt -w .`
-* `pub run test`
-
-If you make changes to `lib/src/config.dart` and need to regenerate
-`lib/src/config.g.dart`:
-
-1. Uncomment the `json_serializable: ^3.0.0` dev dependency in `pubspec.yaml`
-1. Comment out the entirety of `build.yaml`
-1. `pub get && pub run build_runner build`
+See the [Contributing Guidelines][contributing].
 
-This is necessary because a builder cannot depend on code that is generated by
-another builder in the same package. An alternative solution would be to define
-the `TestHtmlBuilderConfig` in a separate package, but this is simpler for now.
+[contributing]: /CONTRIBUTING.md

example/README.md

@@ -0,0 +1,7 @@
+# Example
+
+The [`project/` directory][project] contains an example project that consumes
+this `test_html_builder`. You should be able to run tests in this directory via
+`pub run build_runner test` and have them all pass.
+
+[project]: project/

example/project/build.yaml

@@ -0,0 +1,10 @@
+targets:
+  $default:
+    builders:
+      test_html_builder:
+        options:
+          templates:
+            "test/script_template.html":
+              - "test/script_test.dart"
+            "test/css_template.html":
+              - "test/css_test.dart"

example/project/dart_test.yaml

@@ -0,0 +1,2 @@
+platforms:
+  - chrome

example/project/lib/script.js

@@ -0,0 +1 @@
+window.custom = true;

example/project/lib/style.css

@@ -0,0 +1,3 @@
+body {
+    color: red;
+}

example/project/pubspec.yaml

@@ -0,0 +1,9 @@
+name: test_html_builder_example_project
+version: 0.0.0
+
+dev_dependencies:
+  build_runner: ^1.7.1
+  build_test: ^0.10.9
+  build_web_compilers: ^2.6.3
+  test: ^1.8.0
+  test_html_builder: ^1.0.0

example/project/test/css_template.html

@@ -0,0 +1,6 @@
+<html>
+    <head>
+        <link rel="stylesheet" href="packages/test_html_builder_example_project/style.css"></script>
+        {test}
+    </head>
+</html>

example/project/test/css_test.dart

@@ -0,0 +1,10 @@
+@TestOn('browser')
+import 'dart:html';
+
+import 'package:test/test.dart';
+
+void main() {
+  test('css is loaded', () {
+    expect(document.head.querySelector('link'), isNotNull);
+  });
+}

example/project/test/custom_html_test.custom.html

@@ -0,0 +1,7 @@
+<html>
+  <head>
+    <link rel="x-dart-test" href="custom_html_test.dart">
+    <script src="packages/test/dart.js"></script>
+  </head>
+  <body id="custom"></body>
+</html>

example/project/test/custom_html_test.dart

@@ -0,0 +1,10 @@
+@TestOn('browser')
+import 'dart:html';
+
+import 'package:test/test.dart';
+
+void main() {
+  test('custom ID', () {
+    expect(document.body.id, 'custom');
+  });
+}

example/project/test/no_html_test.dart

@@ -0,0 +1,7 @@
+import 'package:test/test.dart';
+
+void main() {
+  test('passes', () {
+    expect(true, isTrue);
+  });
+}

example/project/test/script_template.html

@@ -0,0 +1,6 @@
+<html>
+    <head>
+        <script src="packages/test_html_builder_example_project/script.js"></script>
+        {test}
+    </head>
+</html>

example/project/test/script_test.dart

@@ -0,0 +1,10 @@
+@TestOn('browser')
+import 'dart:js';
+
+import 'package:test/test.dart';
+
+void main() {
+  test('js is loaded', () {
+    expect(context['custom'], isTrue);
+  });
+}

lib/builder.dart

@@ -18,6 +18,7 @@ import 'package:json_annotation/json_annotation.dart';
 import 'package:test_html_builder/src/builder.dart';
 import 'package:test_html_builder/src/config.dart';
 
+/// Builder factory referenced by this builder's build.yaml definition.
 TestHtmlBuilder testHtmlBuilder(BuilderOptions options) {
   try {
     final config = TestHtmlBuilderConfig.fromJson(options.config);

lib/src/builder.dart

@@ -23,6 +23,11 @@ const _outputExtension = '_test.html';
 
 final _log = Logger('TestHtmlBuilder');
 
+/// Builder that uses templates to generate HTML files for dart tests.
+///
+/// Useful for projects with many tests that require custom HTML. Instead of
+/// having to replicate the custom HTML file for every test file that requires
+/// it, this builder can apply a template to any number of test files.
 class TestHtmlBuilder implements Builder {
   TestHtmlBuilderConfig _config;
 
@@ -78,7 +83,7 @@ class TestHtmlBuilder implements Builder {
       return;
     }
 
-    htmlContents = htmlContents.replaceFirst(
+    htmlContents = htmlContents.replaceAll(
         '{test}',
         '<link rel="x-dart-test" href="${p.basename(buildStep.inputId.path)}">'
             '<script src="packages/test/dart.js"></script>');

pubspec.yaml

@@ -1,5 +1,5 @@
 name: test_html_builder
-version: 1.0.1
+version: 1.0.2
 homepage: https://github.com/Workiva/test_html_builder
 
 description: >