84daaaf94a
Addresses the lack of options we currently have for surfacing issues in
our application via debugging tools. Prioritizes performance and
usability (visually) over clarity in some places that could have been
object mapped.
A logger with three separate audiences:
* `internal`: Logs for developers maintaining Theatre.js
* `dev`: Logs for developers using Theatre.js
* `public`: Logs for everyone
This logger supports:
* multiple logging levels (error, warn, debug, trace),
* multiple audience levels (internal, dev, public),
* multiple categories (general, todo, troubleshooting)
* named and keyed loggers (e.g.
`rootLogger.named("Project", project.id)`)
* console styling with deterministic coloring
* console devtool maintains accurate sourcemap link to logging origin
(e.g. `coreExports.ts:71` as opposed to `logger.ts:45` or whatever)
* swappable logger
* customizable filtering
* Accepts lazy `args`: `args: () => object` via
`logger.lazy.<level>("message", () => <expensive computation>)` (e.g.
`logger.lazy.debugDev("Loaded project state", () => ({ save: bigProject.exportToSaveable() }))`)
|
||
|---|---|---|
| .. | ||
| devEnv | ||
| src | ||
| .gitignore | ||
| LICENSE | ||
| package.json | ||
| README.md | ||
| tsconfig.json | ||
| vercel.json | ||
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 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.
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 .gitignored. Note that every playground must include an entry file called index.tsx (as you see in the Directory structure section).
How to write and run end-to-end tests
The end-to-end tests are in the src/tests folder. Look at directory structure to see how test files are organized.
The end-to-end tests are made using playwright. You should refer to playwright's documentation
$ 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, first serve the playground and then run the codegen on the a url that points to the playground you wish to test:
$ 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 for visual regression testing. These tests run only the the CI using Github actions. Look at the example at 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.