Merge branch 'main' into feat/renderloop_optimizations

.eslintrc.cjs

@@ -24,6 +24,7 @@ const config = {
       './tsconfig.vitest.json',
       './tsconfig.cfg.json',
       './examples/tsconfig.json',
+      './visual-regression/tsconfig.json',
     ],
     // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
     tsconfigRootDir: __dirname,

.github/workflows/tests.yml

@@ -0,0 +1,48 @@
+on:
+  - pull_request
+
+jobs:
+  run-all-tests:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+
+      - name: Install Node.js
+        uses: actions/setup-node@v3
+        with:
+          node-version: 20
+
+      - uses: pnpm/action-setup@v2
+        name: Install pnpm
+        with:
+          version: 8
+          run_install: false
+
+      - name: Get pnpm store directory
+        shell: bash
+        run: |
+          echo "STORE_PATH=$(pnpm store path --silent)" >> $GITHUB_ENV
+
+      - uses: actions/cache@v3
+        name: Setup pnpm cache
+        with:
+          path: ${{ env.STORE_PATH }}
+          key: ${{ runner.os }}-pnpm-store-${{ hashFiles('**/pnpm-lock.yaml') }}
+          restore-keys: |
+            ${{ runner.os }}-pnpm-store-
+
+      - name: Install dependencies
+        run: pnpm install
+
+      - name: Run Unit Tests
+        run: pnpm test
+
+      - name: Install Playwright Browser
+        run: cd visual-regression && pnpm exec playwright install chromium
+
+      - name: Run Visual Regression Tests
+        run: pnpm run test:visual --color
+        env:
+          RUNTIME_ENV: ci

.gitignore

@@ -6,10 +6,13 @@ dist
 dist-cfg
 dist-vitest
 examples/dist-tsc
+visual-regression/failed-results
+visual-regression/certified-snapshots/*-local
 build
 releases
 .tmp
 .env
 *.tgz
+.pnpm-store
 # This project uses `pnpm` for package management
 package-lock.json

.husky/pre-commit

@@ -1,4 +1,10 @@
 #!/usr/bin/env sh
 . "$(dirname -- "$0")/_/husky.sh"
 
-npx lint-staged
+# If files exist in the `visual-regression/failed-results` directory, fail the commit
+if [ -n "$(ls -A visual-regression/failed-results)" ]; then
+  echo "Failed Visual Regression Test results found in \`visual-regression/failed-results\`. Please fix them before committing."
+  exit 1
+fi
+
+pnpm exec lint-staged

.npmrc

@@ -1 +1,2 @@
 engine-strict = true
+use-node-version = 20.9.0

Dockerfile

@@ -0,0 +1,18 @@
+# Use Playwright's base image
+FROM mcr.microsoft.com/playwright:v1.39.0-jammy
+
+# Set the working directory
+WORKDIR /work
+
+# Install PNPM
+RUN npm install -g pnpm
+
+# Copy the necessary files to the container
+COPY .npmrc .npmrc
+COPY package.json package.json
+
+# Get pnpm to install the version of Node declared in .npmrc
+RUN pnpm exec ls
+
+# Set the entry point command
+CMD ["/bin/bash", "-c", "echo 'Must run with Visual Regression Test Runner: `pnpm run test:visual --ci`'"]

README.md

@@ -25,21 +25,53 @@ pnpm watch
 # Run unit tests
 pnpm test
 
+# Run Visual Regression Tests
+pnpm test:visual
+
 # Build API Documentation (builds into ./docs folder)
 pnpm typedoc
 
-# Launch test examples in dev mode (includes Build Renderer (watch mode))
+# Launch Example Tests in dev mode (includes Build Renderer (watch mode))
 pnpm start
 
-# Launch test examples in production mode
+# Launch Example Tests in production mode
 # IMPORTANT: To run test examples on embedded devices that use older browser versions
 # you MUST run the examples in this mode.
 pnpm start:prod
 ```
 
-## Test Examples
+## Example Tests
+
+The Example Tests sub-project define a set of tests for various Renderer
+features. This is NOT an automated test. The command below will launch a
+web server which can be accessed by a web browser for manual testing. However,
+many of the Example Tests define Snapshots for the Visual Regression Test Runner
+(see below).
+
+The Example Tests can be launched with:
+
+```
+pnpm start
+```
+
+See [examples/README.md](./examples/README.md) for more info.
+
+## Visual Regression Tests
+
+In order to prevent bugs on existing Renderer features when new features or bug
+fixes are added, the Renderer includes a Visual Regression Test Runner along
+with a set of certified snapshot files that are checked into the repository.
+
+These tests can be launched with:
+
+```
+pnpm test:visual
+```
+
+The captured Snapshots of these tests are optionally defined in the individual
+Example Tests.
 
-See [examples/README.md](./examples/README.md)
+See [visual-regression/README.md](./visual-regression/README.md) for more info.
 
 ## Release Procedure
 
@@ -87,14 +119,14 @@ The Main Core Driver renders your application on the web page's main thread.
 It can be configured into the Renderer like so:
 
 ```ts
-import { MainRenderDriver, RendererMain } from '@lightningjs/renderer';
+import { MainCoreDriver, RendererMain } from '@lightningjs/renderer';
 
 const renderer = new RendererMain(
   {
     // App Config
   },
   'app', // App div ID
-  new MainRenderDriver(), // Main Render driver
+  new MainCoreDriver(), // Main Render driver
 );
 
 // ...
@@ -109,7 +141,7 @@ It can be configured into the Renderer like so:
 
 ```ts
 import {
-  ThreadXRenderDriver,
+  ThreadXCoreDriver,
   RendererMain,
 } from '@lightningjs/renderer';
 
@@ -121,7 +153,7 @@ const renderer = new RendererMain(
     // App Config
   },
   'app', // App div ID
-  new ThreadXRenderDriver({
+  new ThreadXCoreDriver({
     coreWorkerUrl,
   });
 );

examples/.npmrc

@@ -0,0 +1 @@
+engine-strict = true

examples/README.md

@@ -1,13 +1,15 @@
-# Lightning 3 Renderer Test Examples
+# Example Tests
 
-This directory contains a set of independent examples which can be selected via
-URL parameters.
+This directory contains a set of independent Example Tests which can be selected
+via URL parameters for manual testing.
+
+Many of these Example Tests also define Snapshots for the Visual Regression Test
+Runner. See [visual-regression/README.md](../visual-regression/README.md) for
+more information on how those tests are run and how their Snapshots are defined.
 
 ## Setup
 
 ```
-pnpm install
-
 # Run code in dev mode (includes building Renderer in watch mode)
 pnpm start
 
@@ -33,10 +35,21 @@ pnpm watch
 
 ## URL Params
 
-- `test` - Test example to run
+- `test` (string, default: "test")
+  - Test example to run.
   - Can be any of the file names (minus extension) in the `tests` directory.
-- `driver` - Core driver to use
+- `driver` (string, default: "main")
+  - Core driver to use
   - Either `main` or `threadx`
+- `overlay` (boolean, default: "true")
+  - Whether or not to show the text overlay in the bottom-right corner that
+    displays the current test and driver being used.
+- `automation` (boolean, default: "false")
+  - Automation mode.
+  - Executes the exported `automation()` function for every Example Test
+    that defines one, one after the other.
+  - This is used by the Visual Regression Test Runner.
+  - See [visual-regression/README.md](../visual-regression/README.md) for more info.
 
 ## Note on imports
 

examples/common/ExampleSettings.ts

@@ -17,11 +17,43 @@
  * limitations under the License.
  */
 
-import type { Dimensions, RendererMain } from '@lightningjs/renderer';
+import type { INode, RendererMain } from '@lightningjs/renderer';
 
 export interface ExampleSettings {
+  /**
+   * Name of the test being run.
+   */
   testName: string;
+  /**
+   * Renderer instance
+   */
   renderer: RendererMain;
+  /**
+   * Core Driver being used by the test.
+   */
   driverName: 'main' | 'threadx';
-  canvas: HTMLCanvasElement;
+  /**
+   * The HTML Element that the Renderer's canvas is a child of
+   */
+  appElement: HTMLDivElement;
+  /**
+   * Renderer Node that all tests should use as their root node.
+   *
+   * @remarks
+   * Tests should NEVER use the `renderer.root` node as this will prevent the
+   * automation mode from being able to clean up after each test.
+   */
+  testRoot: INode;
+  /**
+   * Whether the test is being run in automation mode.
+   */
+  automation: boolean;
+  /**
+   * If the test is run in automation mode, this method will take a visual
+   * snapshot of the current state of the renderer's canvas for the Visual
+   * Regression Test Runner.
+   *
+   * This method will be a no-op if the test is not run in automation mode.
+   */
+  snapshot(): Promise<void>;
 }