Prettify READMEs and minor formatting tweaks

README.md

@@ -513,7 +513,6 @@ see [./test/cypress#readme](./test/cypress#readme).
 
 For an overview of all testing see [./test#readme](./test#readme)
 
-
 ### Gitflow
 
 VideoContext uses the gitflow branching model.
@@ -540,15 +539,15 @@ CI will publish to npm when the release branch has been merged into master.
 2. `git pull`
 3. `git checkout -b release-xxx`
 4. tag and push using script
-    - `npm run release:patch|minor|major`
+   - `npm run release:patch|minor|major`
 5. open pull request against master
 6. merge when tests have passed
 7. merge master back in to develop:
-    - `git checkout master`
-    - `git pull`
-    - `git checkout develop`
-    - `git merge master`
-    - `git push`
+   - `git checkout master`
+   - `git pull`
+   - `git checkout develop`
+   - `git merge master`
+   - `git push`
 
 There is one housekeeping task (this will be automated at some point):
 

test/README.md

@@ -4,32 +4,31 @@
 ![cypress](https://img.shields.io/badge/testing-cypress-informational.svg)
 ![jest](https://img.shields.io/badge/testing-jest-informational.svg?style=flat&logo=jest)
 
-
 There are three approaches to testing within `VideoContext`. All must pass on CI for PRs to be merged.
 
 ### [🔗unit](./unit)
 
 Testing the individual components that make up `VideoContext` as isolated units
 
-- __framework__: [jest](https://jestjs.io/)
-- __coverage__: moderate
-- __coupling__: high - we're using a reasonable amount of mocking and testing against some private APIs
+- **framework**: [jest](https://jestjs.io/)
+- **coverage**: moderate
+- **coupling**: high - we're using a reasonable amount of mocking and testing against some private APIs
 
 ### [🔗integration](./integration)
 
 Spec testing on the public APIs of `VideoContext`
 
-- __framework__: [jest](https://jestjs.io/)
-- __coverage__: moderate/low
-- __coupling__: low
+- **framework**: [jest](https://jestjs.io/)
+- **coverage**: moderate/low
+- **coupling**: low
 
 ### [🔗cypress](./cypress)
 
 End-to-end regression testing in the browser. `VideoContext` is driven as it would be in the real world.
-Cypress is used to take and compare screenshots out the output to previous builds 
+Cypress is used to take and compare screenshots out the output to previous builds
 
-- __framework__: [cypress](https://www.cypress.io/)
-- __coverage__: low
-- __coupling__: low
+- **framework**: [cypress](https://www.cypress.io/)
+- **coverage**: low
+- **coupling**: low
 
 For more detail see [./cypress#readme](./cypress#readme)

test/cypress/html/index.html

@@ -17,4 +17,4 @@
     </script>
 </body>
 
-</html>
+</html>

test/cypress/integration/effects.spec.js

@@ -22,7 +22,7 @@ it("Color Threshold", () => {
         colorThresholdEffect.connect(ctx.destination);
     });
 
-    // check output matches the snapshots at times on the timeline
+    // Check output matches the snapshots at times on the timeline
     cy.videoContextScreenShotsAtTimes(SCREEN_SHOT_TIMES, { id: "effect-color-threshold" });
 });
 
@@ -43,7 +43,7 @@ it("Crop", () => {
         cropEffect.connect(ctx.destination);
     });
 
-    // check output matches the snapshots at times on the timeline
+    // Check output matches the snapshots at times on the timeline
     cy.videoContextScreenShotsAtTimes(SCREEN_SHOT_TIMES, { id: "effect-crop" });
 });
 
@@ -60,7 +60,7 @@ it("Horizontal Blur", () => {
         horizontalBlurEffect.connect(ctx.destination);
     });
 
-    // check output matches the snapshots at times on the timeline
+    // Check output matches the snapshots at times on the timeline
     cy.videoContextScreenShotsAtTimes(SCREEN_SHOT_TIMES, { id: "effect-horizontal-blur" });
 });
 
@@ -77,7 +77,7 @@ it("Monochrome", () => {
         monochromeEffect.connect(ctx.destination);
     });
 
-    // check output matches the snapshots at times on the timeline
+    // Check output matches the snapshots at times on the timeline
     cy.videoContextScreenShotsAtTimes(SCREEN_SHOT_TIMES, { id: "effect-monochrome" });
 });
 
@@ -94,7 +94,7 @@ it("Opacity", () => {
         opacityEffect.connect(ctx.destination);
     });
 
-    // check output matches the snapshots at times on the timeline
+    // Check output matches the snapshots at times on the timeline
     cy.videoContextScreenShotsAtTimes(SCREEN_SHOT_TIMES, { id: "effect-opacity" });
 });
 
@@ -111,7 +111,7 @@ it("Static", () => {
         staticEffect.connect(ctx.destination);
     });
 
-    // check output matches the snapshots at times on the timeline
+    // Check output matches the snapshots at times on the timeline
     cy.videoContextScreenShotsAtTimes(SCREEN_SHOT_TIMES, { id: "effect-static" });
 });
 
@@ -128,6 +128,6 @@ it("Vertical Blur", () => {
         verticalBlurEffect.connect(ctx.destination);
     });
 
-    // check output matches the snapshots at times on the timeline
+    // Check output matches the snapshots at times on the timeline
     cy.videoContextScreenShotsAtTimes(SCREEN_SHOT_TIMES, { id: "effect-vertical-blur" });
 });

test/cypress/integration/playback.spec.js

@@ -4,49 +4,49 @@ beforeEach(() => {
 });
 
 it("plays back video", () => {
-    // set up VideoContext
+    // Set up VideoContext
     cy.window().then(({ ctx }) => {
-        const videoNode = ctx.video("../assets/video1.webm"); // path relative to index.html
+        const videoNode = ctx.video("../assets/video1.webm"); // Path relative to index.html
         videoNode.startAt(0);
         videoNode.connect(ctx.destination);
     });
 
-    // check output  match the snapshots at times on the timeline
+    // Check output  match the snapshots at times on the timeline
     cy.videoContextScreenShotsAtTimes([0.5, 1, 1.5], { id: "playback-video" });
 });
 
 it("plays back image", () => {
-    // set up VideoContext
+    // Set up VideoContext
     cy.window().then(({ ctx }) => {
         const imageNode = ctx.image("../assets/test-image.png");
         imageNode.startAt(0);
         imageNode.connect(ctx.destination);
     });
 
-    // check output  match the snapshots at times on the timeline
+    // Check output  match the snapshots at times on the timeline
     cy.videoContextScreenShotsAtTimes([0.5, 1, 1.5], { id: "playback-image" });
 });
 
 it("plays back image with no creatImageBitmap", () => {
-    // set up VideoContext
+    // Set up VideoContext
     cy.window().then(win => {
         const ctx = win.ctx;
-        // remove createImageBitmap to simulate being in a browser with no support
+        // Remove createImageBitmap to simulate being in a browser with no support
         win.createImageBitmap = undefined;
 
         const imageNode = ctx.image("../assets/test-image.png");
         imageNode.startAt(0);
         imageNode.connect(ctx.destination);
     });
 
-    // check output  match the snapshots at times on the timeline
+    // Check output  match the snapshots at times on the timeline
     cy.videoContextScreenShotsAtTimes([0.5, 1, 1.5], {
         id: "playback-image-with-no-createImageBitmap"
     });
 });
 
 it("plays back  with user supplied element and start offset", () => {
-    // set up VideoContext
+    // Set up VideoContext
     cy.window().then(win => {
         const ctx = win.ctx;
         const video = win.document.createElement("video");
@@ -60,7 +60,7 @@ it("plays back  with user supplied element and start offset", () => {
         videoNode.connect(ctx.destination);
     });
 
-    // check output  match the snapshots at times on the timeline
+    // Check output  match the snapshots at times on the timeline
     cy.videoContextScreenShotsAtTimes([0.5, 1, 1.5], {
         id: "playback-user-supplied-element"
     });

test/cypress/snapshots/.gitignore

@@ -1 +1 @@
-All*Specs/
+All*Specs/

test/cypress/support/videoContextScreenShotsAtTimesCommand.js

@@ -1,5 +1,17 @@
 /**
- * to update snapshots run: `yarn run cypress:update`
+ * takeScreenShotAtTime
+ *
+ * Capture and compare a frame with an existing snapshot
+ * for a specific time.
+ *
+ * To update snapshots run:
+ *  - CI: `yarn cypress:update-snapshots`
+ *  - GUI: `yarn cypress:gui-update-snapshots`
+ *
+ * See the README.md for more information.
+ *
+ * @param {number} time at which to take snapshots (in seconds)
+ * @param {{ ctx: object, id: string, options: object }} options - `ctx` VideoContext, `id` unique id to name snapshots, `options` matchImageSnapshot config overrides
  */
 const takeScreenShotAtTime = (time, { ctx, id, options }) =>
     new Promise(resolve => {
@@ -10,20 +22,20 @@ const takeScreenShotAtTime = (time, { ctx, id, options }) =>
          */
         ctx.currentTime = time - 0.005;
 
-        // start playback
+        // Start playback
         ctx.play();
 
-        // register a callback at the time we want to snapshot
+        // Register a callback at the time we want to snapshot
         ctx.registerTimelineCallback(time, () => {
             console.log("snapshot at time", time, ctx.currentTime - time);
-            // stop the player from progressing past this frame
+            // Stop the player from progressing past this frame
             ctx.pause();
 
             resolve(
-                // we must return a cypress chain
+                // We must return a cypress chain
                 cy
                     .get("#canvas")
-                    // compare this frame with the snapshot
+                    // Compare this frame with the snapshot
                     .matchImageSnapshot(`${id} at time ${time}`, options)
             );
         });
@@ -39,16 +51,16 @@ const takeScreenShotAtTime = (time, { ctx, id, options }) =>
  *
  *
  * @param {Array<number>} times at which to take snapshots (in seconds)
- * @param {{ id: string }} options `id`: unique id to name snapshots
+ * @param {{ id: string, options: object }} options `id`: unique id to name snapshots
  */
 const videoContextScreenShotsAtTimes = (times = [1, 25, 50], { id, options }) => {
-    // use a closure to access window
+    // Use a closure to access window
     let window;
 
-    // we're going to chain on this promise
+    // We're going to chain on this promise
     let cyPromise = cy.window();
 
-    // prepare by starting playback and storing the window object
+    // Prepare by starting playback and storing the window object
     cyPromise = cyPromise.then(win => {
         /**
          * We slow down the playback rate to increase the chance of the registered
@@ -63,14 +75,14 @@ const videoContextScreenShotsAtTimes = (times = [1, 25, 50], { id, options }) =>
         window = win;
     });
 
-    // reduce over the times taking a screen-shot when each time is reached
+    // Reduce over the times taking a screen-shot when each time is reached
     times.forEach(time => {
         cyPromise = cyPromise.then({ timeout: 10000 }, () =>
             takeScreenShotAtTime(time, { ctx: window.ctx, id, options })
         );
     });
 
-    // last, rest the context so that playback and updates stop
+    // Last, rest the context so that playback and updates stop
     return cyPromise.then(() => {
         window.ctx.reset();
     });