diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml
index 901fcbe..8fba319 100644
--- a/.github/workflows/main.yml
+++ b/.github/workflows/main.yml
@@ -37,3 +37,13 @@ jobs:
- run: yarn typecheck
- run: yarn lint:all
- run: yarn test
+ - name: Download playwright
+ run: yarn workspace playground run playwright install
+ - name: Run e2e tests
+ run: yarn test:e2e
+ - name: Run e2e tests with percy
+ uses: percy/exec-action@v0.3.1
+ with:
+ custom-command: 'yarn test:e2e:ci'
+ env:
+ PERCY_TOKEN: ${{ secrets.PERCY_TOKEN }}
diff --git a/.gitignore b/.gitignore
index 11d0e4c..c6df9e5 100644
--- a/.gitignore
+++ b/.gitignore
@@ -17,4 +17,5 @@
!.yarn/plugins
!.yarn/releases
!.yarn/sdks
-!.yarn/versions
\ No newline at end of file
+!.yarn/versions
+
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 8abe2ba..a9e6f23 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -41,11 +41,12 @@ The quickest way to start tweaking things is to run the `playground` package.
```sh
$ cd ./packages/playground
$ yarn serve
+# or, shortcut:
+$ cd root
+$ yarn playground
```
-The playground is a bunch of ready-made projects that you can run to experiment with Theatre.js.
-
-It uses a single ESBuild config to build all of the related packages in one go, so you don't have to run a bunch of build commands separately.
+The playground is a bunch of ready-made projects that you can run to experiment with Theatre.js. It also contains the project's end-to-end tests.
Read more at [`./packages/playground/README.md`](./packages/playground/README.md).
@@ -65,7 +66,7 @@ $ cd examples/dom-cra
$ yarn start
```
-### Running tests
+### Running unit/integration tests
We use a single [jest](https://jestjs.io/) setup for the repo. The tests files have the `.test.ts` or `.test.tsx` extension.
@@ -78,6 +79,10 @@ $ yarn test
$ yarn test --watch
```
+### Running end-to-end tests
+
+End-to-end tests are hosted in the playground package. More details [there](./packages/playground/README.md).
+
### Type checking
The packages in this repo have full typescript coverage, so you should be able to get diagnostics and intellisense if your editor supports typescript.
diff --git a/package.json b/package.json
index 445d836..c863140 100644
--- a/package.json
+++ b/package.json
@@ -9,6 +9,8 @@
],
"scripts": {
"playground": "yarn workspace playground run serve",
+ "test:e2e": "yarn workspace playground run test",
+ "test:e2e:ci": "yarn workspace playground run test:ci",
"typecheck": "yarn run build:ts",
"build": "zx scripts/build.mjs",
"build:ts": "tsc --build ./devEnv/typecheck-all-projects/tsconfig.all.json",
diff --git a/packages/playground/.gitignore b/packages/playground/.gitignore
index 3e22129..018675f 100644
--- a/packages/playground/.gitignore
+++ b/packages/playground/.gitignore
@@ -1 +1,3 @@
-/dist
\ No newline at end of file
+/dist
+/test-results/
+/playwright-report/
\ No newline at end of file
diff --git a/packages/playground/README.md b/packages/playground/README.md
index 4e36bba..e9606aa 100644
--- a/packages/playground/README.md
+++ b/packages/playground/README.md
@@ -1,12 +1,58 @@
# The playground
-The playground is the quickest way to hack on the internals of Theatre. It uses a simple ESBuild config that builds all the related packages in one go, so you _don't_ have to run a bunch of build commands separately to start developing.
+The playground is the quickest way to hack on the internals of Theatre. It also hosts our end-to-end tests. It uses a simple vite config that builds all the related packages in one go, so you _don't_ have to run a bunch of build commands separately to start developing.
-## How to use
+## Directory structure
+
+```
+src/
+ shared/ <---- playgrounds shared with teammates.
+ [playground-name]/ <---- each playground has a name...
+ index.tsx <---- and an entry file.
+
+ personal/ <---- personal playgrounds (gitignored).
+ [playground-name]/ <---- personal playgrounds also have names,
+ index.tsx <---- and an entry file.
+
+ tests/ <---- playgrounds for e2e testing.
+ [playground-name]/ <---- the name of the test playground,
+ index.tsx <---- and its entry file.
+ [test-file-name].e2e.ts <---- The playwright test script that tests this particular playground.
+ [test2].e2e.ts <---- We can have more than one test file per playground.
+```
+
+## How to use the playground
Simply run `yarn run serve` in this folder to start the dev server.
-The first time you run `serve`, an `src/index.ts` file will be created. This file is the entry point, and it won't be comitted to the repo, so you're free to change it.
+There are some shared playgrounds in `src/shared` which are committed to the repo. You can make your own playgrounds in `src/personal` which will be `.gitignore`d. Each
-There are some shared playgrounds in `src/shared` which are committed to the repo. You can make your own playgrounds in `src/personal` which will be `.gitignore`d.
+## How to write and run end-to-end tests
+The end-to-end tests are in the `src/tests` folder. Look at [directory structure](#directory-structure) to see how test files are organized.
+
+The end-to-end tests are made using [playwright](https://playwright.dev). You should refer to playwright's documentation
+
+```bash
+$ cd playground
+$ yarn test # runs the end-to-end tests
+$ yarn test --project=firefox # only run the tests in firefox
+$ yarn test --project=firefox --headed # run the test in headed mode in firefox
+$ yarn test --debug # run in debug mode using the inspector: https://playwright.dev/docs/inspector
+```
+
+### Using playwright codegen
+
+To use [playwright's codegen tool](https://playwright.dev/docs/codegen), first serve the playground and then run the codegen on the a url that points to the playground you wish to test:
+
+```bash
+$ cd playground
+$ yarn serve # first serve the playground
+$ yarn playwright codegen http://localhost:8080/tests/[playground-name] # run the codegen for [playground-name]
+```
+
+## Visual regression testing
+
+We're currently using [percy](https://percy.io) for visual regression testing. These tests run only the the [CI](../../.github/workflows/main.yml) using [Github actions](https://github.com/theatre-js/theatre/actions). Look at the example at [`src/tests/setting-static-props/test.e2e.ts`](src/tests/setting-static-props/test.e2e.ts) for an example of recording and diffing a screenshot.
+
+Please note that we haven't figured out the best practices for visual regression testing yet, so if the setup isn't optimal, please let us know.
\ No newline at end of file
diff --git a/packages/playground/devEnv/playwright-report/index.html b/packages/playground/devEnv/playwright-report/index.html
new file mode 100644
index 0000000..185f643
--- /dev/null
+++ b/packages/playground/devEnv/playwright-report/index.html
@@ -0,0 +1,3 @@
+Playwright Test Report
\ No newline at end of file
diff --git a/packages/playground/devEnv/playwright.config.ts b/packages/playground/devEnv/playwright.config.ts
new file mode 100644
index 0000000..f0a1743
--- /dev/null
+++ b/packages/playground/devEnv/playwright.config.ts
@@ -0,0 +1,77 @@
+import type {PlaywrightTestConfig} from '@playwright/test'
+import {devices} from '@playwright/test'
+
+/**
+ * Read environment variables from file.
+ * https://github.com/motdotla/dotenv
+ */
+// require('dotenv').config();
+
+/**
+ * See https://playwright.dev/docs/test-configuration.
+ */
+const config: PlaywrightTestConfig = {
+ testDir: '../src',
+ testMatch: /.*\.e2e\.ts/,
+ /* Maximum time one test can run for. */
+ timeout: 100000,
+ expect: {
+ /**
+ * Maximum time expect() should wait for the condition to be met.
+ * For example in `await expect(locator).toHaveText();`
+ */
+ timeout: 10000,
+ },
+ /* Fail the build on CI if you accidentally left test.only in the source code. */
+ forbidOnly: !!process.env.CI,
+ /* Retry on CI only */
+ retries: process.env.CI ? 0 : 0,
+ /* Opt out of parallel tests on CI. */
+ workers: process.env.CI ? 1 : undefined,
+ /* Reporter to use. See https://playwright.dev/docs/test-reporters */
+ reporter: process.env.CI ? 'github' : 'html',
+ /* Shared settings for all the projects below. See https://playwright.dev/docs/api/class-testoptions. */
+ use: {
+ /* Maximum time each action such as `click()` can take. Defaults to 0 (no limit). */
+ // actionTimeout: 200,
+ /* Base URL to use in actions like `await page.goto('/')`. */
+ // baseURL: 'http://localhost:3000',
+
+ /* Collect trace when retrying the failed test. See https://playwright.dev/docs/trace-viewer */
+ trace: 'on-first-retry',
+ },
+
+ /* Configure projects for major browsers */
+ projects: [
+ {
+ name: 'chromium',
+ use: {
+ ...devices['Desktop Chrome'],
+ },
+ },
+
+ {
+ name: 'firefox',
+ use: {
+ ...devices['Desktop Firefox'],
+ },
+ },
+ ],
+
+ /* Folder for test artifacts such as screenshots, videos, traces, etc. */
+ outputDir: '../test-results/',
+
+ /*
+ This will serve the playground before running the tests, unless the playground is already running.
+
+ Note that if the playground is not running but some other server is serving at port 8080, this will fail.
+ TODO 👆
+ */
+ webServer: {
+ command: 'yarn run serve',
+ port: 8080,
+ reuseExistingServer: !process.env.CI,
+ },
+}
+
+export default config
diff --git a/packages/playground/devEnv/vite.config.ts b/packages/playground/devEnv/vite.config.ts
index 0ce6750..fcf3ede 100644
--- a/packages/playground/devEnv/vite.config.ts
+++ b/packages/playground/devEnv/vite.config.ts
@@ -3,7 +3,6 @@ import react from '@vitejs/plugin-react'
import path from 'path'
import {getAliasesFromTsConfigForRollup} from '../../../devEnv/getAliasesFromTsConfig'
import {definedGlobals} from '../../../theatre/devEnv/buildUtils'
-import {existsSync, writeFileSync} from 'fs'
/*
We're using vite instead of the older pure-esbuild setup. The tradeoff is
@@ -18,36 +17,10 @@ const playgroundDir = path.join(__dirname, '..')
const port = 8080
-/**
- * Creates playground/src/index.ts, since that file isn't committed to the repo.
- */
-function createPlaygroundIndex() {
- const playgroundIndexContent = `
- /**
- * This file is created automatically and won't be comitted to the repo.
- * You can change the import statement and import your own playground code.
- *
- * Your own playground code should reside in './personal', which is a folder
- * that won't be committed to the repo.
- *
- * The shared playgrounds which other contributors can use are in the './shared' folder,
- * which are comitted to the repo.
- *
- * Happy playing!
- * */
- import './shared/r3f-rocket'
- `
-
- const playgroundEntry = path.join(playgroundDir, 'src/index.ts')
- if (!existsSync(playgroundEntry)) {
- writeFileSync(playgroundEntry, playgroundIndexContent, {encoding: 'utf-8'})
- }
-}
-createPlaygroundIndex()
-
// https://vitejs.dev/config/
export default defineConfig({
root: path.join(playgroundDir, './src'),
+
assetsInclude: ['**/*.gltf', '**/*.glb'],
server: {
port,
@@ -61,5 +34,5 @@ export default defineConfig({
*/
alias: [...getAliasesFromTsConfigForRollup()],
},
- define: definedGlobals,
+ define: {...definedGlobals, 'window.__IS_VISUAL_REGRESSION_TESTING': 'true'},
})
diff --git a/packages/playground/package.json b/packages/playground/package.json
index c41c771..b74ea35 100644
--- a/packages/playground/package.json
+++ b/packages/playground/package.json
@@ -10,9 +10,14 @@
"scripts": {
"serve": "vite --config ./devEnv/vite.config.ts",
"typecheck": "yarn run build",
+ "test": "playwright test --config=devEnv/playwright.config.ts",
+ "test:ci": "percy exec -- playwright test --reporter=dot --config=devEnv/playwright.config.ts --project=chromium",
"build": "tsc --build ./tsconfig.json"
},
"devDependencies": {
+ "@percy/cli": "^1.0.0-beta.76",
+ "@percy/playwright": "^1.0.1",
+ "@playwright/test": "^1.19.1",
"@react-three/drei": "^7.2.2",
"@react-three/fiber": "^7.0.6",
"@theatre/core": "workspace:*",
diff --git a/packages/playground/src/.gitignore b/packages/playground/src/.gitignore
index 5e71368..1a6df4b 100644
--- a/packages/playground/src/.gitignore
+++ b/packages/playground/src/.gitignore
@@ -1,2 +1 @@
-personal
-index.ts
\ No newline at end of file
+personal
\ No newline at end of file
diff --git a/packages/playground/src/index.html b/packages/playground/src/index.html
index b51f922..7ceafd1 100644
--- a/packages/playground/src/index.html
+++ b/packages/playground/src/index.html
@@ -8,6 +8,13 @@
padding: 0;
height: 100%;
background: black;
+ color: white;
+ font-family: sans-serif;
+ font-size: 12px;
+ }
+
+ a {
+ color: inherit;
}
@@ -15,6 +22,6 @@
-
+