Update readme with common workflows and patterns (#21196)
## Common Workflows and Patterns This section contains common workflows and patterns to increase inner dev loop efficiency. ### Build - `pnpm install` from the root of the repository to install dependencies. This is necessary for new clones or after pulling changes from the main branch. - `pnpm run build:fast` from the root of the repository to perform an incremental build that matches the CI build process. Incremental builds tend to leave extra files laying around, so running a clean is sometimes needed to cleanup ghost tests - `pnpm run build:fast -- <path>` to build only a specific part of the repository. - `pnpm run build` within a package directory to build that package. - `pnpm run build:compile` for cross-package compilation. - `pnpm run format` to format the code. - `fluid-build --vscode` to output error message to work with default problem matcher in vscode. If `fluid-build` is not installed, please install it with `npm i -g @fluidframework/build-tools`. #### Multi package setup - `fluid-build -t build <NAME_OF_PACKAGES>` to build a multiple space-separated packages along with all their dependencies. If `fluid-build` is not installed, please install it with `npm i -g @fluidframework/build-tools`. ### Debug - You can also use the VSCode JS debug terminal, then run the test as normal. - Sometimes, uncommitted changes can cause build failures. Committing changes might be necessary to resolve such issues. ### Troubleshooting - `pnpm clean` if random build failures, especially with no changes - `git clean -xdf` to remove extraneous files if debugging becomes slow or hangs. ## Testing You can run all of our tests from the root of the repo, or you can run a scoped set of tests by running the `test` command from the package you're interested in. Note: Some of the tests depend on test collateral that lives in a submodule here: <https://github.com/microsoft/FluidFrameworkTestData>. You may choose to fetch that collateral into your local repository, which is required to run all the tests - otherwise some will be skipped. First, ensure you have installed [Git LFS](https://git-lfs.com/). Then, from the repo root: ```shell git lfs install git submodule init git submodule update ``` ### Run the tests Before running the tests, the project has to be built. Depending on what tests you want to run, execute the following command in the package directory or at the root: ```shell npm run test ``` - To run a single test within a module, add `.only` to `it` or `describe`. To exclude a test, use `.skip`. - You can use `ts-mocha` to quickly run specific test files without needing to make the whole project compile. For more details on test filtering using CLI arguments, refer to the [Mocha documentation](https://mochajs.org/#command-line-usage). - Our test setup generally requires building before running the tests. - Incremental builds may leave extra files, which can result in ghost tests. To avoid this, consider running a clean build with the following command: ```shell pnpm clean <package> ``` This removes any leftover files from previous builds, providing a clean testing environment. [AB#4739](https://dev.azure.com/fluidframework/235294da-091d-4c29-84fc-cdfc3d90890b/_workitems/edit/4739)
This commit is contained in:
Родитель
c9bc72c5a1
Коммит
7dea35e751
44
README.md
44
README.md
|
@ -167,6 +167,36 @@ There are a few different areas in which we generate documentation content as a
|
|||
- We leverage [API-Extractor](https://api-extractor.com/) to generate summaries of our package APIs.
|
||||
This is done as a part of a full build, but it can also be executed in isolation by running `npm run build:api` from the repo root.
|
||||
|
||||
## Common Workflows and Patterns
|
||||
|
||||
This section contains common workflows and patterns to increase inner dev loop efficiency.
|
||||
|
||||
### Build
|
||||
|
||||
- `pnpm install` from the root of the repository to install dependencies. This is necessary for new clones or after pulling changes from the main branch.
|
||||
- `pnpm run build:fast` from the root of the repository to perform an incremental build that matches the CI build process. Incremental builds tend to leave extra files laying around, so running a clean is sometimes needed to cleanup ghost tests
|
||||
- `pnpm run build:fast -- <path>` to build only a specific part of the repository.
|
||||
- `pnpm run build` within a package directory to build that package.
|
||||
- `pnpm run build:compile` for cross-package compilation.
|
||||
- `pnpm run format` to format the code.
|
||||
|
||||
- `fluid-build --vscode` to output error message to work with default problem matcher in vscode. If `fluid-build` is not installed, please install it with `npm i -g @fluidframework/build-tools`.
|
||||
|
||||
#### Multi package setup
|
||||
|
||||
- `fluid-build -t build <NAME_OF_PACKAGES>` to build a multiple space-separated packages along with all their dependencies. If `fluid-build` is not installed, please install it with `npm i -g @fluidframework/build-tools`.
|
||||
|
||||
### Debug
|
||||
|
||||
- You can also use the VSCode JS debug terminal, then run the test as normal.
|
||||
|
||||
- Sometimes, uncommitted changes can cause build failures. Committing changes might be necessary to resolve such issues.
|
||||
|
||||
### Troubleshooting
|
||||
|
||||
- `pnpm clean` if random build failures, especially with no changes
|
||||
- `git clean -xdf` to remove extraneous files if debugging becomes slow or hangs.
|
||||
|
||||
## Testing
|
||||
|
||||
You can run all of our tests from the root of the repo, or you can run a scoped set of tests by running the `test`
|
||||
|
@ -187,10 +217,24 @@ git submodule update
|
|||
|
||||
### Run the tests
|
||||
|
||||
Before running the tests, the project has to be built. Depending on what tests you want to run, execute the following command in the package directory or at the root:
|
||||
|
||||
```shell
|
||||
npm run test
|
||||
```
|
||||
|
||||
- To run a single test within a module, add `.only` to `it` or `describe`. To exclude a test, use `.skip`.
|
||||
- You can use `ts-mocha` to quickly run specific test files without needing to make the whole project compile. For more details on test filtering using CLI arguments, refer to the [Mocha documentation](https://mochajs.org/#command-line-usage).
|
||||
|
||||
- Our test setup generally requires building before running the tests.
|
||||
- Incremental builds may leave extra files, which can result in ghost tests. To avoid this, consider running a clean build with the following command:
|
||||
|
||||
```shell
|
||||
pnpm clean <package>
|
||||
```
|
||||
|
||||
This removes any leftover files from previous builds, providing a clean testing environment.
|
||||
|
||||
### Include code coverage
|
||||
|
||||
```shell
|
||||
|
|
Загрузка…
Ссылка в новой задаче