Installation

From CLI

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

setup 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 proposed file structure
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).

Continue to Install instructions

Manual setup

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.3.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 native Vitest config allowing 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.0.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.

Install and execute

Whether you used the CLI tool or did the manual setup, you are ready to install and run the tests.

1) Install the dependencies:

It is advised to remove node_modules and delete the lock file first. Then proceed with a fresh installation.

2) 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 (the CLI tool can do this for you as its last step):

pnpm exec playwright-core install

npx playwright-core install

yarn playwright-core install

bunx playwright-core install

deno run -A npm:playwright-core install

3) Start the development server of your Nuxt project:

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

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 package manager's update command (e.g. pnpm update nuxt-spec@0.3.2) to bump nuxt-spec to the latest version
run the playwright-core install command to ensure the Playwright browser runtimes are up to date

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-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-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-i   # runs and waits in HMR mode

yarn test        # runs once and ends
yarn test-u      # runs once and updates snapshots
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-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-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.

More info

Continue to the configuration to see how you can adjust the default settings.
See changelog to display the latest changes.
Visit contributing guide if you want to help with development.

Installation ​

From CLI ​

Manual setup ​

Install and execute ​

Updating ​

Running tests ​

More info ​