Created a 'known failures' test directory. Updated some docs.

Author: matthew-carroll

doc/website/source/golden-scenes/failures.md

@@ -2,13 +2,25 @@
 title: Failures
 navOrder: 40
 ---
-`flutter_test_goldens` improves the review experience for failing golden tests.
+Building on the concept of [Golden Scenes](/golden-scenes/what-is-it), `flutter_test_goldens` introduces
+the concept of "Failure Scenes". A Failure Scene is just like a Golden Scene, except instead of painting
+a collection of goldens, it paints a collection of golden mismatch images.
 
-Golden failures typically generate four files: the golden image, the new screenshot, an isolated
-diff, and a masked diff. These images are useful, but viewing them across four files is tedious.
+In Flutter, golden failures typically generate four files: 
+ * The golden image
+ * The new screenshot
+ * An isolated diff
+ * A masked diff. 
 
-Instead of generating four separate image files upon failure, `flutter_test_goldens` paints
-all four of those failure images as a single image, making it easy to view side-by-side.
+These images are useful, but viewing them across four files is tedious. Not only do you have to
+open and view 4 files to understand 1 failure, but the number of failure files quickly gets out of
+control. Imagine goldens that cover 5 different configurations of a widget. Now, imagine that all
+5 of those golden tests fail. Flutter would generate 5x4 = 20 failure files. This is intractable
+within a production project.
+
+The `golden_toolkit` package improved this issue by placing many different goldens in a single scene.
+As a result, those 5 failures would generate a single failure file. But this approach still had its
+issues - namely.
 
 Moreover, if a Golden Scene contains more than one golden image, all failure images for all
 goldens in the scene, are painted to the same image. This provides the most holistic view

doc/website/source/golden-scenes/gallery.md

@@ -7,26 +7,19 @@ and/or widget configurations.
 
 ```dart
 await Gallery(
-    tester,
-    sceneName: "button_extended_fab_gallery",
-    layout: SceneLayout.row,
-    itemDecorator: (context, child) {
-      return FlutterWidgetScaffold(
-        child: child,
-      );
-    },
+    "Extended FAB",
+    fileName: "button_extended_fab_gallery",
+    layout: ColumnSceneLayout(),
   )
     .itemFromWidget(
-      id: "1",
       description: "Icon + Text",
       widget: FloatingActionButton.extended(
         icon: Icon(Icons.edit),
         label: Text("Hello"),
-          onPressed: () {},
+        onPressed: () {},
       ),
     )
     .itemFromWidget(
-      id: "2",
       description: "Icon",
       widget: FloatingActionButton.extended(
         icon: Icon(Icons.edit),
@@ -35,12 +28,11 @@ await Gallery(
       ),
     )
     .itemFromWidget(
-      id: "3",
       description: "Text",
       widget: FloatingActionButton.extended(
-      label: Text("Hello"),
-      onPressed: () {},
+        label: Text("Hello"),
+        onPressed: () {},
       ),
     )
-    .renderOrCompareGolden();
+    .run(tester);
 ```

doc/website/source/golden-scenes/filmstrip.md renamed to doc/website/source/golden-scenes/timeline.md

@@ -1,32 +1,32 @@
 ---
-title: Filmstrip
+title: Timeline
 navOrder: 30
 ---
-A filmstrip is a Golden Scene, which displays a widget at different points in
+A timeline is a Golden Scene, which displays a widget at different points in
 time, and possibly across various user interactions.
 
 ```dart
-await FilmStrip(
-  tester,
-  goldenName: "button_elevated_interactions",
-  layout: SceneLayout.row,
+await Timeline(
+  "Elevated Button Interactions",
+  fileName: "button_elevated_interactions",
+  layout: RowSceneLayout(),
 )
-  .setupWithPump(() {
-    return FlutterWidgetScaffold(
+  .setupWithWidget(
+    FlutterWidgetScaffold(
       goldenKey: goldenKey,
       child: ElevatedButton(
         onPressed: () {},
         child: Text("Hello"),
       ),
-    );
-  })
-  .takePhoto("idle")
+    ),
+  )
+  .takePhoto("Idle")
   // Screenshot the hovered state.
   .hoverOver(find.byType(ElevatedButton))
-  .takePhoto("hover")
+  .takePhoto("Hover")
   // Screenshot the pressed state.
   .pressHover()
-  .takePhoto("pressed")
+  .takePhoto("Pressed")
   // Render or compare the scene.
-  .renderOrCompareGolden();
+  .run(tester);
 ```

doc/website/source/golden-scenes/what-is-it.md

@@ -18,7 +18,7 @@ A Golden Scene with independent golden images, such as different configurations
 widget, is called a [Gallery](/golden-scenes/gallery).
 
 A Golden Scene with golden images that take place over time, such as the idle, hovered, and
-pressed state of a button, is called a [Film Strip](/golden-scenes/filmstrip).
+pressed state of a button, is called a [Timeline](/golden-scenes/timeline).
 
 ## What makes Golden Scenes different?
 Fans of golden tests are no doubt familiar with `golden_toolkit`, a package by eBay Motors,
@@ -50,4 +50,4 @@ What if you want to capture the idle state, the hover state, and the pressed sta
 
 `flutter_test_goldens` includes the concept of a `GoldenCamera`, which allows developers to take screenshots
 over a period of time. Those screenshots can then be stitched together into a Golden Scene, such as
-with a [`FilmStrip`](/golden-scenes/filmstrip).
+with a [`Timeline`](/golden-scenes/timeline).