Installation

From CLI

The nuxt-spec package comes with a built-in CLI tool that can help you:

set up the dependency in your project
scaffold the default vitest.config.ts (see configuration section)
add some test-related shorthands in your package.json (see running tests section)
create demo test files in the proposed file structure
add nuxt-spec-related entries to your .gitignore
generate the Nuxt types and auto-imports (via nuxt prepare) so the project is ready to use
install the Playwright browser runtimes needed to run the e2e tests

To use it, just run the CLI script in your terminal:

First, the CLI tool will ask you whether you want to do the setup automatically. If you choose yes, it will perform all the steps for you. If you choose no, it will guide you through the manual setup step-by-step (see manual setup section).

The CLI tool can also scaffold CI workflows for GitHub or GitLab via the separate ci command. See CI integration for details.

Manual setup

TIP: If you already ran the automated setup, you can skip this section.

If you don't want to use the CLI tool, or you want to understand its flow better, here are detailed explanations of the required/recommended steps:

1) Add the following dependency to your package.json:

package.json

json

"nuxt-spec": "0.4.0-alpha.2"

It is also advised to remove all explicit nuxt, vue, and vue-router dependencies, if present. The nuxt-spec layer includes all of them, and there might be version clashes if they are defined in both places.

2) Add the following section to your nuxt.config.ts:

nuxt.config.ts

extends: [
  'nuxt-spec'
]

3) If pnpm is used, add a pnpm-workspace.yaml file with the following content (if you don't have it yet):

pnpm-workspace.yaml

yaml

shamefullyHoist: true

This will ensure the dependencies will be pulled into your project without having to explicitly define them in your package.json file.

4) Add a vitest.config.ts file with the following content (if you don't have it yet):

vitest.config.ts

import { loadVitestConfig } from 'nuxt-spec/config'

export default loadVitestConfig({
  // your custom config here
})

This is a wrapper around the native Vitest config, allowing you to merge your custom configs with nuxt-spec defaults. See configuration section for more info.

5) Add a .nuxtrc file with the following content (if you don't have it yet):

.nuxtrc

text

setups.@nuxt/test-utils="4.3.3"

Nuxt will auto-generate the file anyway if you do not create it.

6) (Optional) Add the following scripts to your package.json:

package.json

json

"scripts": {
  "test": "vitest run",
  "test-u": "vitest run -u",
  "test-i": "vitest"
}

Those are just shorthands for running tests which you may or may not want to use.

7) (Optional) Set up the file structure for tests as follows:

text

test/
├── browser/
│   └── vitest-browser.test.ts
├── e2e/
│   └── nuxt-e2e.test.ts
│   └── nuxt-visual.test.ts
├── nuxt/
│   └── nuxt-unit.test.ts
└── unit/
    └── vitest-unit.test.ts

You can use sample files from the project repository.

The structure matches the default configuration of nuxt-spec.

8) Add the following entries to your .gitignore:

.gitignore

# vitest output folder
.vitest

# vitest coverage output folder
coverage

# nuxt-spec screenshots folder
__current__

# nuxt-spec HTML test reports folder
__reports__

Those folders contain files generated during test runs that are not necessary to be committed.

9) Install the dependencies:

It is advised to remove node_modules and delete the lock file first to avoid resolution issues.

Then proceed with a fresh installation:

10) Run the Nuxt preparation step to generate the required types and auto-imports:

This is required so all auto-generated files are emitted and all the features and type inference work properly.

11) If you're prompted (for the first time when installing on a new machine, or after a version update), install the headless browser runtimes locally:

pnpm exec playwright install

npx playwright install

yarn playwright install

bunx playwright install

deno run -A npm:playwright install

Updating

If nuxt-spec is already installed in your project, you can use the same CLI tool with the update command to update the existing installation:

It works the same way as setup - first asking whether to run automatically, then either performing all the steps or asking for confirmation before each one. If nuxt-spec is not found in your package.json, it will fail and ask you to run setup first.

The update command will:

run the package manager's update command (e.g. pnpm update nuxt-spec@0.4.0-alpha.2) to bump nuxt-spec to the latest version
run the nuxt prepare command to regenerate the Nuxt types and auto-imports
run the playwright install command to ensure the Playwright browser runtimes are up to date
bump the Playwright container image version in CI files scaffolded by the ci command (see CI integration)

Running tests

Once installed, Vitest automatically discovers all *.test.ts and *.spec.ts files in the project and becomes capable of running them.

You can use those three optional commands in your package.json file in the "scripts" section in order to run tests easily:

test: vitest run - runs once and ends
test-u: vitest run -u - runs once and updates snapshots
test-c: vitest run --coverage - runs once and displays coverage report (see code coverage)
test-i: vitest - runs and waits in HMR mode for test file changes

Then you can run them from the root of your project:

pnpm test        # runs once and ends
pnpm test-u      # runs once and updates snapshots
pnpm test-c      # runs once and displays coverage
pnpm test-i      # runs and waits in HMR mode

npm run test     # runs once and ends
npm run test-u   # runs once and updates snapshots
npm run test-c   # runs once and displays coverage
npm run test-i   # runs and waits in HMR mode

yarn test        # runs once and ends
yarn test-u      # runs once and updates snapshots
yarn test-c      # runs once and displays coverage
yarn test-i      # runs and waits in HMR mode

bun run test     # runs once and ends
bun run test-u   # runs once and updates snapshots
bun run test-c   # runs once and displays coverage
bun run test-i   # runs and waits in HMR mode

deno task test    # runs once and ends
deno task test-u  # runs once and updates snapshots
deno task test-c  # runs once and displays coverage
deno task test-i  # runs and waits in HMR mode

Or you can use the vitest command directly with all its parameters. See Vitest CLI documentation for more info.

Known issues

There might be situations that cannot be effectively solved on the Nuxt Spec side and require manual action in the target project.

Currently, there are no known problems.
Open an issue, if you encounter one.

More info

Continue to the configuration to see how you can adjust the default settings.
See CI integration to run your tests in GitHub Actions or GitLab CI/CD.
See the changelog to view the latest changes.
Visit the contributing guide if you want to help with development.

Installation ​

From CLI ​

Manual setup ​

Updating ​

Running tests ​

Known issues ​

More info ​