68 lines
No EOL
3.5 KiB
Markdown
68 lines
No EOL
3.5 KiB
Markdown
# The playground
|
|
|
|
The playground is the quickest way to hack on the internals of Theatre. It also hosts our end-to-end tests. It uses a build setup (see the live-reload esbuild server in [./devEnv/build.ts](./devEnv/build.ts)) 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.
|
|
|
|
## 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.
|
|
|
|
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. Note that every playground must include an entry file called `index.tsx` (as you see in the [Directory structure section](#directory-structure)).
|
|
|
|
## 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
|
|
|
|
Some `.e2e.ts` files also contain visual regression tetst. 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.
|
|
|
|
Note that CI runs the visual regression tests in a linux VM, which is bound to produce a slightly different screenshot than a browser on Mac/Windows. Because of that, we have a `docker-compose.yml` file at the root of the repo which you can use to produce a screenshot in a linux vm. Here is how you can use it:
|
|
|
|
```bash
|
|
$ cd repo
|
|
$ docker-compose up -d # start the linux vm
|
|
$ docker-compose exec -it node bash # ssh into the vm
|
|
$ yarn
|
|
$ yarn test:e2e:ci
|
|
```
|
|
|
|
If you're submitting a PR that breaks the visual regression tests and you're not familiar with Docker, simply ask the mainainers to update the screenshots for you. |