-
-
Notifications
You must be signed in to change notification settings - Fork 70
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
Showing
2 changed files
with
51 additions
and
10 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,18 +1,57 @@ | ||
# Contributing Guide | ||
|
||
## pnpm | ||
## Repo setup | ||
|
||
This project uses pnpm to manage monorepo. You should run `pnpm i` after cloning this repo. | ||
This repo uses [pnpm](https://pnpm.io/) to manage monorepo. | ||
|
||
## Tests | ||
1. Run `pnpm install` in the repo root folder to install and link dependencies. | ||
2. Run `pnpm run build` in the repo root folder to build all packages. You can also do that manually by running `pnpm run build` in folders `packages/react-pages` and `packages/theme-doc`. | ||
3. Run `pnpm run dev` in the repo root folder to build and watch all packages. You can also do that manually by running `pnpm run dev` in folders `packages/react-pages` and `packages/theme-doc`. It will rebuild automatically whenever you change the package source code. So we prefer `pnpm run dev` to `pnpm run build` when changing source code frequently. | ||
|
||
The test setup is copied from [vite](https://github.com/vitejs/vite/blob/f6b58a0f535b1c26f9c1dfda74c28c685402c3c9/jest.config.js#L1). Fixtures and test cases is under `packages/playground`. | ||
|
||
> There must be no more than one `.spec.ts` file for each fixture. Otherwise it will cause Error like `Error: EEXIST: file already exists, mkdir '/home/csr/vite-plugin-react-pages/temp/basic'`. There is some flaws with current test setup (which is copied from vite's repo). | ||
## Run playgrounds | ||
## Running playgrounds | ||
|
||
```sh | ||
cd packages/playground/basic/ # or other playgrounds | ||
npm run dev | ||
cd packages/playground/use-theme-doc/ # or other playgrounds | ||
pnpm run dev | ||
pnpm run build | ||
pnpm run ssr | ||
``` | ||
|
||
## Debugging | ||
|
||
To use breakpoints and explore code execution, you can use the ["Run and Debug"](https://code.visualstudio.com/docs/editor/debugging) feature from **VS Code**. | ||
|
||
1. Add a `debugger` statement where you want to stop the code execution. | ||
2. If you add `debugger` to the source code of a package, make sure to use `pnpm run build` or `pnpm run dev` to build the package after modifying the code. | ||
3. Click the "Run and Debug" icon in the activity bar of VS Code, which opens the [_Run and Debug view_](https://code.visualstudio.com/docs/editor/debugging#_run-and-debug-view). | ||
4. Click the "JavaScript Debug Terminal" button in the _Run and Debug view_, which opens a terminal in VS Code. | ||
5. From that terminal, go to `packages/playground/xxx`, and run `pnpm run dev` or `pnpm run build` or `pnpm run ssr`. | ||
6. The execution will stop at the `debugger` statement, and you can use the [Debug toolbar](https://code.visualstudio.com/docs/editor/debugging#_debug-actions) to continue, step over, and restart the process... | ||
|
||
## Running tests | ||
|
||
This project uses [playwright](https://playwright.dev/) to run integration tests. | ||
|
||
If you are running tests for the first time in this repo, you should run `pnpm run install-test-deps` in repo root folder to install test deps. | ||
|
||
After having test deps installed, run `pnpm run test` to run all tests. | ||
Or run `pnpm run test-serve` to run tests in vite serve mode only. | ||
Or run `pnpm run test-build` to run tests in vite build mode only. | ||
Or run `pnpm run test-ssr` to run tests in ssr mode only. | ||
|
||
Run `pnpm run test file-name-filter` to filter on file name. For example, `pnpm run test hmr` will run tests in `packages/playground/use-theme-doc/__tests__/hmr.spec.ts`. | ||
|
||
Adding `--debug` after any test command will make it run in debug mode. For example, `pnpm run test hmr --debug`. With this mode enabled, you can play with browser developer tools, exploring selectors, and stop test with `await page.pause()`. Checkout [playwright debug doc](https://playwright.dev/docs/debug#playwright-inspector) to learn more. | ||
|
||
Checkout more test arguments at [playwright doc](https://playwright.dev/docs/test-cli). Most notable arguments are: | ||
|
||
- `--debug` | ||
- `--max-failures=1` make test stop when it encounter the first error, so that you can tackle one problem at a time. | ||
- `--headed` | ||
- `--workers=1` prevent playwright using multiple thread to run tests in parallel. | ||
|
||
## Writing tests | ||
|
||
Currently all runnable tests are located at `packages/playground/use-theme-doc/__tests__/`. You can see them as examples. | ||
|
||
Test utils are set up at `test-setup/utils/index.ts`. They are [playwright test fixtures](https://playwright.dev/docs/test-fixtures). |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters