[Docs] - Document golden test runners

Author: matthew-carroll

doc/website/source/_data.yaml

@@ -1,3 +1,20 @@
+website:
+  social:
+    opengraph:
+      url: https://fluttergoldens.com
+      title: Flutter Test Goldens
+      description: The best package for writing golden tests.
+      image: https://fluttergoldens.com/images/branding/social.png
+      type: website
+
+    twitter:
+      card: summary_large_image
+      site: "@SuprDeclarative"
+      url: https://fluttergoldens.com
+      title: Flutter Test Goldens
+      description: The best package for writing golden tests.
+      image: https://fluttergoldens.com/images/branding/social.png
+
 # Configuration for the package that this website documents.
 package:
   name: flutter_test_goldens
@@ -37,6 +54,10 @@ navigation:
     - title: "Get Started"
       url: /get-started
 
+    - title: Create a Test
+      tag: create-a-test
+      sortBy: navOrder
+
     - title: Galleries
       tag: gallery
       sortBy: navOrder

doc/website/source/create-a-test/_data.yaml

@@ -0,0 +1 @@
+tags: create-a-test

doc/website/source/create-a-test/test-runners.md

@@ -0,0 +1,68 @@
+---
+title: Test Runners
+---
+Test runners are the methods that are used to declare and define tests. Typically,
+golden tests are defined with the `testWidgets()` test runner. However, `flutter_test_goldens`
+comes with its own test runners for convenience, e.g., `testGoldenScene()`.
+
+## The Standard Test Runner
+The standard test runner in `flutter_test_goldens` is `testGoldenScene()`.
+
+```dart
+void main() {
+  testGoldenScene("my golden test", (tester) async {
+    // TODO: implement golden test.
+  });
+}
+```
+
+The `testGoldenScene()` test runner wraps around Flutter's standard `testWidgets()`
+test runner, while making a few adjustments:
+
+ * Sets the `devicePixelRatio` to `1.0` to unify all test pixel densities, and reduce scaling artifacts.
+ * Sets the `textScaleFactor` to `1.0` to unify all test text scales, and reduce scaling artifacts.
+ * Loads app fonts so that labels and decorations around your goldens are rendered with a real font.
+
+
+## Platform Specific Test Runners
+When writing golden tests, sometimes you may want to simulate a specific platform. For example, maybe
+you want to render a golden of your app with an iOS style UI, specifically. For this purpose,
+`flutter_test_goldens` provides per-platform test runners.
+
+```dart
+void main() {
+  testGoldenSceneOnIOS("my iOS golden test", (tester) async {
+    // TODO: implement golden test.
+  });
+
+  testGoldenSceneOnAndroid("my Android golden test", (tester) async {
+    // TODO: implement golden test.
+  });
+
+  testGoldenSceneOnMac("my Mac golden test", (tester) async {
+    // TODO: implement golden test.
+  });
+
+  testGoldenSceneOnWindow("my Windows golden test", (tester) async {
+    // TODO: implement golden test.
+  });
+
+  testGoldenSceneOnLinux("my Linux golden test", (tester) async {
+    // TODO: implement golden test.
+  });
+}
+```
+
+The implementation of the platform-specific test runners are nearly identical to `testGoldenScene()`, except
+they set the `debugDefaultTargetPlatformOverride` property to the given platform.
+
+```dart
+debugDefaultTargetPlatformOverride = TargetPlatform.macOS;
+```
+
+When the test completes, `debugDefaultTargetPlatformOverride` is reset to `null`.
+
+You could implement this behavior yourself, within the standard `testWidgets()` runner, but
+these platform-specific test runners are provided as a convenient way to simulate a platform without
+repeating the platform configuration every time.
+

doc/website/source/get-started.md

@@ -1,14 +1,32 @@
 ---
 title: Get Started
 ---
+## Add the Package
 To get started with `flutter_test_goldens`, add the package to your pubspec.
 
 ```yaml
 dev_dependencies:
   flutter_test_goldens: any
 ```
 
-With the packaged added, you may want to accomplish a variety of goals:
+## Start a Test
+Define a test using the `testGoldenScene()` method, or a related test runner.
+
+```dart
+void main() {
+  testGoldenScene("my golden test", (tester) async {
+    // TODO: implement golden test.
+  });
+}
+```
+
+Using `flutter_test_goldens` test runners isn't strictly required, but they handle some test
+configuration that's expected for a golden test.
+
+[Learn more](/create-a-test/test-runners) about `flutter_test_goldens` test runners.
+
+## Implement a Test
+With a test ready to go, you may want to accomplish a variety of goals:
 
  * [Write a gallery test](/golden-scenes/gallery)
  * [Write a timeline test](/golden-scenes/filmstrip)