You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
docs: upgrades for Vitest doc and add with-vitest example (#10063)
### Description
Some iterations for our Vitest documentation:
- Made it clearer that this document is for interactions of Vitest and
Turborepo, not just "Vitest in monorepos"
- Fixed commands that were wrong
- A new `with-vitest` example
- A section on merged coverage reports
- Other minor wording fixes
Closes#4517
### Reviewer note
The example does exactly one thing that I don't love, in that it doesn't
have dependencies between `turbo run test` and the set of tasks that do
the merging/reporting of coverage after that. This means you have to do
`turbo run test && whatever-else` rather than a singular `turbo`
command.
I don't know if there's a great way to model this in our DSL right now,
so I left it out. Ultimately, running `turbo run test && ...` isn't too
big of a deal, right?...Right?
### Testing Instructions
👀
---------
Co-authored-by: Chris Olszewski <[email protected]>
[Vitest](https://vitest.dev/) is a test runner from the Vite ecosystem. Integrating it with Turborepo will lead to enormous speed-ups.
12
12
13
-
<CreateTurboCallout />
13
+
[The Vitest documentation](https://vitest.dev/guide/workspace) shows how to create a "Vitest Workspace" that runs all tests in the monorepo from one root command, enabling behavior like merged coverage reports out-of-the-box. This feature doesn't follow modern best practices for monorepos, since its designed for compatibility with Jest (whose Workspace feature was built before [package manager Workspaces](/repo/docs/crafting-your-repository/structuring-a-repository)).
14
14
15
-
## Setting up
15
+
Because of this you have two options, each with their own tradeoffs:
16
16
17
-
Let's say we have a monorepo that looks like this:
17
+
-[Leveraging Turborepo for caching](#leveraging-turborepo-for-caching)
To improve on cache hit rates and only run tests with changes, you can choose to configure tasks per-package, splitting up the Vitest command into separate, cacheable scripts in each package. This speed comes with the tradeoff that you'll need to create merged coverage reports yourself.
23
+
24
+
<Callout>
25
+
For a complete example, run `npx create-turbo@latest --example with-vitest` or
Let's say we have a simple [package manager Workspace](/repo/docs/crafting-your-repository/structuring-a-repository) that looks like this:
18
33
19
34
<Files>
20
35
<Foldername="apps"defaultOpen>
@@ -29,12 +44,15 @@ Let's say we have a monorepo that looks like this:
29
44
</Folder>
30
45
</Files>
31
46
32
-
Both `apps/web` and `packages/ui` have their own test suite. Their `package.json` files include a `test` script that runs Vitest:
47
+
Both `apps/web` and `packages/ui` have their own test suites, with `vitest`[installed into the packages that use them](/repo/docs/crafting-your-repository/managing-dependencies#install-dependencies-where-theyre-used). Their `package.json` files include a `test` script that runs Vitest:
33
48
34
49
```json title="./apps/web/package.json"
35
50
{
36
51
"scripts": {
37
-
"test": "vitest"
52
+
"test": "vitest run"
53
+
},
54
+
"devDependencies": {
55
+
"vitest": "latest"
38
56
}
39
57
}
40
58
```
@@ -44,55 +62,66 @@ Inside the root `turbo.json`, create a `test` task:
44
62
```json title="./turbo.json"
45
63
{
46
64
"tasks": {
47
-
"test": {}
65
+
"test": {
66
+
"dependsOn": ["transit"]
67
+
},
68
+
"transit": {
69
+
"dependsOn": ["^transit"]
70
+
}
48
71
}
49
72
}
50
73
```
51
74
52
-
Now, `turbo test` can parallelize and cache all of the test suites from each package, only testing code that has changed.
75
+
Now, `turbo run test` can parallelize and cache all of the test suites from each package, only testing code that has changed.
76
+
77
+
#### Running tests in watch mode
53
78
54
-
## Running tests in watch mode
79
+
When you run your test suite in CI, it logs results and eventually exits upon completion. This means you can [cache it with Turborepo](/repo/docs/crafting-your-repository/caching). But when you run your tests using Vitest's watch mode during development, the process never exits. This makes a watch task more like a [long-running, development task](/repo/docs/crafting-your-repository/developing-applications).
55
80
56
-
When you run your test suite normally, it completes and outputs to `stdout`. This means you can [cache it](/repo/docs/crafting-your-repository/caching) with Turborepo.
81
+
Because of this difference, we recommend specifying **two separate Turborepo tasks**: one for running your tests, and one for running them in watch mode.
57
82
58
-
But when you run your tests in a watched mode, the process never exits. This makes a watch task more like a [development task](/repo/docs/crafting-your-repository/developing-applications).
83
+
<Callout>
84
+
This strategy below creates two tasks, one for local development and one for
85
+
CI. You could choose to make the `test` task for local development and create
86
+
some `test:ci` task instead.
87
+
</Callout>
59
88
60
-
Because of this difference, we recommend specifying **two separate Turborepo tasks**: one for running your tests, and one for running them in watch mode. Inside your each`package.json` file for each workspace:
89
+
For example, inside the`package.json` file for each workspace:
61
90
62
91
```json title="./apps/web/package.json"
63
92
{
64
93
"scripts": {
65
-
"test": "vitest",
94
+
"test": "vitest run",
66
95
"test:watch": "vitest --watch"
67
96
}
68
97
}
69
98
```
70
99
71
-
Inside the root `turbo.json`:
100
+
And, inside the root `turbo.json`:
72
101
73
102
```json title="./turbo.json"
74
103
{
75
104
"tasks": {
76
-
"test": {},
105
+
"test": {
106
+
"dependsOn": ["^test"]
107
+
},
77
108
"test:watch": {
78
-
"cache": false,// [!code highlight]
79
-
"persistent": true// [!code highlight]
109
+
"cache": false,
110
+
"persistent": true
80
111
}
81
112
}
82
113
}
83
114
```
84
115
85
-
You can now either run this task using [global `turbo`](/repo/docs/getting-started/installation#global-installation) as `turbo test:watch` or from a script in your root `package.json`:
116
+
You can now run your tasks using [global `turbo`](/repo/docs/getting-started/installation#global-installation) as `turbo run test:watch` or from a script in your root `package.json`:
86
117
87
118
<Tabsitems={["Global turbo", "./package.json"]}>
88
119
<Tabvalue="Global turbo">
89
120
90
121
```bash title="Terminal"
91
-
turbo test
92
-
```
122
+
turbo run test
93
123
94
-
```bash title="Terminal"
95
-
turbo test:watch
124
+
turbo run test:watch
96
125
```
97
126
98
127
</Tab>
@@ -111,3 +140,75 @@ turbo test:watch
111
140
</Tab>
112
141
113
142
</Tabs>
143
+
144
+
#### Creating merged coverage reports
145
+
146
+
[Vitest's Workspace feature](#using-vitests-workspace-feature) creates an out-of-the-box coverage report that merges all of your packages' tests coverage reports. Following the Turborepo strategy, though, you'll have to merge the coverage reports yourself.
shows a complete example that you may adapt for your needs. You can get
189
+
started with it quickly using `npx create-turbo@latest --example with-vitest`.
190
+
</Callout>
191
+
192
+
### Using Vitest's Workspace feature
193
+
194
+
The Vitest Workspace feature doesn't follow the same model as a [package manager Workspace](/repo/docs/crafting-your-repository/structuring-a-repository). Instead, it uses a root script that then reaches out into each package in the repository to handle the tests in that repsective package.
195
+
196
+
In this model, there aren't package boundaries, from a modern JavaScript ecosystem perspective. This means you can't rely on Turborepo's caching, since Turborepo leans on those package boundaries.
197
+
198
+
Because of this, you'll need to use [Root Tasks](/repo/docs/crafting-your-repository/configuring-tasks#registering-root-tasks) if you want to run the tests using Turborepo. Once you've configured [a Vitest Workspace](https://vitest.dev/guide/workspace), create the Root Tasks for Turborepo:
199
+
200
+
```json title="./turbo.json"
201
+
{
202
+
"tasks": {
203
+
"//#test": {
204
+
"outputs": ["coverage/**"]
205
+
},
206
+
"//#test:watch": {
207
+
"cache": false,
208
+
"persistent": true
209
+
}
210
+
}
211
+
}
212
+
```
213
+
214
+
**Notably, the file inputs for a Root Task include all packages by default, so any change in any package will result in a cache miss.** While this does make for a simplified configuration to create merged coverage reports, you'll be missing out on opportunities to cache repeated work.
This Turborepo starter is maintained by the Turborepo core team.
4
+
5
+
## Using this example
6
+
7
+
This example is based on the `basic` example (`npx create-turbo@latest`) to demonstrate how to use Vitest and get the most out of Turborepo's caching.
8
+
9
+
For this reason, the only commands in the root package.json are `turbo run test` and `turbo run view-report`.
10
+
11
+
`turbo run test`: Runs the test in each package using Turborepo.
12
+
`turbo run view-report`: Collects coverage from each package and shows it in a merged report.
13
+
14
+
### Remote Caching
15
+
16
+
> [!TIP]
17
+
> Vercel Remote Cache is free for all plans. Get started today at [vercel.com](https://vercel.com/signup?/signup?utm_source=remote-cache-sdk&utm_campaign=free_remote_cache).
18
+
19
+
Turborepo can use a technique known as [Remote Caching](https://turbo.build/repo/docs/core-concepts/remote-caching) to share cache artifacts across machines, enabling you to share build caches with your team and CI/CD pipelines.
20
+
21
+
By default, Turborepo will cache locally. To enable Remote Caching you will need an account with Vercel. If you don't have an account you can [create one](https://vercel.com/signup?utm_source=turborepo-examples), then enter the following commands:
22
+
23
+
```
24
+
cd my-turborepo
25
+
npx turbo login
26
+
```
27
+
28
+
This will authenticate the Turborepo CLI with your [Vercel account](https://vercel.com/docs/concepts/personal-accounts/overview).
29
+
30
+
Next, you can link your Turborepo to your Remote Cache by running the following command from the root of your Turborepo:
This is a [Next.js](https://nextjs.org) project bootstrapped with [`create-next-app`](https://nextjs.org/docs/app/api-reference/create-next-app).
2
+
3
+
## Getting Started
4
+
5
+
First, run the development server:
6
+
7
+
```bash
8
+
npm run dev
9
+
# or
10
+
yarn dev
11
+
# or
12
+
pnpm dev
13
+
# or
14
+
bun dev
15
+
```
16
+
17
+
Open [http://localhost:3000](http://localhost:3000) with your browser to see the result.
18
+
19
+
You can start editing the page by modifying `app/page.tsx`. The page auto-updates as you edit the file.
20
+
21
+
This project uses [`next/font`](https://nextjs.org/docs/app/building-your-application/optimizing/fonts) to automatically optimize and load Inter, a custom Google Font.
22
+
23
+
## Learn More
24
+
25
+
To learn more about Next.js, take a look at the following resources:
26
+
27
+
-[Next.js Documentation](https://nextjs.org/docs) - learn about Next.js features and API.
28
+
-[Learn Next.js](https://nextjs.org/learn) - an interactive Next.js tutorial.
29
+
30
+
You can check out [the Next.js GitHub repository](https://github.com/vercel/next.js) - your feedback and contributions are welcome!
31
+
32
+
## Deploy on Vercel
33
+
34
+
The easiest way to deploy your Next.js app is to use the [Vercel Platform](https://vercel.com/new?utm_medium=default-template&filter=next.js&utm_source=create-next-app&utm_campaign=create-next-app-readme) from the creators of Next.js.
35
+
36
+
Check out our [Next.js deployment documentation](https://nextjs.org/docs/app/building-your-application/deploying) for more details.
0 commit comments