nuxt-spec 0.2.0-alpha.2 → 0.2.0-alpha.3

package/README.md

@@ -37,7 +37,7 @@ If you don't want to use the CLI tool, or you want to understand its flow better
 1) Add following dependency into your `package.json`:
 
 ```
-"nuxt-spec": "0.2.0-alpha.2"
+"nuxt-spec": "0.2.0-alpha.3"
 ```
 
 2) Add following section into your `nuxt.config.ts`:
@@ -89,7 +89,7 @@ test/
     └── vitest-unit.test.ts
 ```
 
-You can use sample files from the [project repository](https://github.com/AloisSeckar/nuxt-spec/tree/v0.2.0-alpha.2/test).
+You can use sample files from the [project repository](https://github.com/AloisSeckar/nuxt-spec/tree/v0.2.0-alpha.3/test).
 
 ### Install and execute
 
@@ -249,11 +249,11 @@ Planned future development:
 - reason about (not) using Vitest browser mode (or make it optional)
 - solution for visual regression testing - (currently there is experimental custom solution)
 
-See [CHANGELOG.md](https://github.com/AloisSeckar/nuxt-spec/blob/v0.2.0-alpha.2/CHANGELOG.md) for the latest updates and features.
+See [CHANGELOG.md](https://github.com/AloisSeckar/nuxt-spec/blob/v0.2.0-alpha.3/CHANGELOG.md) for the latest updates and features.
 
 ## Configuration
 
-By default, `nuxt-spec` uses Vitest configuration defined in [`/config/index.mjs`](https://github.com/AloisSeckar/nuxt-spec/blob/v0.2.0-alpha.2/config/index.mjs). The configuration is based on [Nuxt team recommendations](https://nuxt.com/docs/4.x/getting-started/testing) and our best judgement.
+By default, `nuxt-spec` uses Vitest configuration defined in [`/config/index.mjs`](https://github.com/AloisSeckar/nuxt-spec/blob/v0.2.0-alpha.3/config/index.mjs). The configuration is based on [Nuxt team recommendations](https://nuxt.com/docs/4.x/getting-started/testing) and our best judgement.
 
 To add/override your custom config, you can create (or scaffold via CLI tool) a file named `vitest.config.ts` in the root of your project with the following content:
 
@@ -313,7 +313,15 @@ import { compareScreenshot, gotoPage, getDataHtml, getAPIResultHtml, } from 'nux
 // takes a screenshot of current viewport and compares it with stored baseline
 // if screenshot doesn't exist, it will be created as baseline
 // if screenshots don't match, the method will cause Vitest test to fail
-await compareScreenshot(page, 'screenshot.png')
+// accepts optional object with extra options:
+// - `fileName` - name of the screenshot file (default is based on current route)
+// - `selector` - CSS selector of the element to capture (default is full page)
+// - `targetDir` - directory where the screenshots should be stored (default is `./test/e2e/`)
+
+await compareScreenshot(page) // will produce "index.png" file in `./test/e2e/` directory
+await compareScreenshot(page, { fileName: 'homepage.png' }) // will produce "homepage.png"
+await compareScreenshot(page, { fileName: 'component.png', selector: '#test' }) // will produce "component.png" only with id="test" element
+await compareScreenshot(page, { fileName: 'homepage.png', targetDir: '/screenshots' }) // will produce "homepage.png" in `/screenshots` directory
 
 // navigates to given URL and returns the instance of NuxtPage (from @nuxt/test-utils)
 const page: NuxtPage = await gotoPage('url')
@@ -333,7 +341,7 @@ const html: string = await getAPIResultHtml('/', '#api-fetch', '/your-api', '#ap
 const html: string = await getAPIResultHtml(page, '#api-fetch', '/your-api', '#api-result')
 ```
 
-For detailed description, see [utils.d.ts](https://github.com/AloisSeckar/nuxt-spec/blob/v0.2.0-alpha.2/utils/index.d.ts).
+For detailed description, see [utils.d.ts](https://github.com/AloisSeckar/nuxt-spec/blob/v0.2.0-alpha.3/utils/index.d.ts).
 
 ## Contact
 

package/bin/setup.js

@@ -37,7 +37,7 @@ export async function specSetup(autoRun = false) {
   // add nuxt-spec
   try {
     await updateJsonFile('package.json', 'dependencies', {
-      'nuxt-spec': '0.2.0-alpha.2',
+      'nuxt-spec': '0.2.0-alpha.3',
     }, isAutoRun, 'This will add \'nuxt-spec\' dependency to your \'package.json\'. Continue?')
   } catch (error) {
     console.error('Error adding \'nuxt-spec\' dependency:\n', error.message)
@@ -107,7 +107,7 @@ export async function specSetup(autoRun = false) {
       if (pathExists('.npmrc')) {
         await updateTextFile('.npmrc', ['shamefully-hoist=true'], isAutoRun, 'This will adjust \'.npmrc\' file in your project. Continue?')
       } else {
-        await createFileFromWebTemplate('https://raw.githubusercontent.com/AloisSeckar/nuxt-spec/refs/tags/v0.2.0-alpha.2/.npmrc',
+        await createFileFromWebTemplate('https://raw.githubusercontent.com/AloisSeckar/nuxt-spec/refs/tags/v0.2.0-alpha.3/.npmrc',
           '.npmrc', isAutoRun, 'This will add \'.npmrc\' file for your project. Continue?')
       }
     } catch (error) {
@@ -117,7 +117,7 @@ export async function specSetup(autoRun = false) {
 
   // 4) create vitest.config.ts
   try {
-    await createFileFromWebTemplate('https://raw.githubusercontent.com/AloisSeckar/nuxt-spec/refs/tags/v0.2.0-alpha.2/config/vitest.config.ts.template',
+    await createFileFromWebTemplate('https://raw.githubusercontent.com/AloisSeckar/nuxt-spec/refs/tags/v0.2.0-alpha.3/config/vitest.config.ts.template',
       'vitest.config.ts', isAutoRun, 'This will create a new \'vitest.config.ts\' file for your project. Continue?')
   } catch (error) {
     console.error('Error setting up \'vitest.config.ts\':\n', error.message)
@@ -155,31 +155,31 @@ export async function specSetup(autoRun = false) {
   const createSampleTests = isAutoRun || await promptUser('Do you want to create sample tests in \'/test\' folder?')
   if (createSampleTests) {
     try {
-      await createFileFromWebTemplate('https://raw.githubusercontent.com/AloisSeckar/nuxt-spec/refs/tags/v0.2.0-alpha.2/test/browser/vitest-browser.test.ts',
+      await createFileFromWebTemplate('https://raw.githubusercontent.com/AloisSeckar/nuxt-spec/refs/tags/v0.2.0-alpha.3/test/browser/vitest-browser.test.ts',
         'test/browser/vitest-browser.test.ts', true)
     } catch (error) {
       console.error('Error setting up \'vitest-browser.test.ts\':\n', error.message)
     }
     try {
-      await createFileFromWebTemplate('https://raw.githubusercontent.com/AloisSeckar/nuxt-spec/refs/tags/v0.2.0-alpha.2/test/e2e/nuxt-e2e.test.ts',
+      await createFileFromWebTemplate('https://raw.githubusercontent.com/AloisSeckar/nuxt-spec/refs/tags/v0.2.0-alpha.3/test/e2e/nuxt-e2e.test.ts',
         'test/e2e/nuxt-e2e.test.ts', true)
     } catch (error) {
       console.error('Error setting up \'nuxt-e2e.test.ts\':\n', error.message)
     }
     try {
-      await createFileFromWebTemplate('https://raw.githubusercontent.com/AloisSeckar/nuxt-spec/refs/tags/v0.2.0-alpha.2/test/e2e/nuxt-visual.test.ts',
+      await createFileFromWebTemplate('https://raw.githubusercontent.com/AloisSeckar/nuxt-spec/refs/tags/v0.2.0-alpha.3/test/e2e/nuxt-visual.test.ts',
         'test/e2e/nuxt-visual.test.ts', true)
     } catch (error) {
       console.error('Error setting up \'nuxt-visual.test.ts\':\n', error.message)
     }
     try {
-      await createFileFromWebTemplate('https://raw.githubusercontent.com/AloisSeckar/nuxt-spec/refs/tags/v0.2.0-alpha.2/test/nuxt/nuxt-unit.test.ts',
+      await createFileFromWebTemplate('https://raw.githubusercontent.com/AloisSeckar/nuxt-spec/refs/tags/v0.2.0-alpha.3/test/nuxt/nuxt-unit.test.ts',
         'test/nuxt/nuxt-unit.test.ts', true)
     } catch (error) {
       console.error('Error setting up \'nuxt-unit.test.ts\':\n', error.message)
     }
     try {
-      await createFileFromWebTemplate('https://raw.githubusercontent.com/AloisSeckar/nuxt-spec/refs/tags/v0.2.0-alpha.2/test/unit/vitest-unit.test.ts',
+      await createFileFromWebTemplate('https://raw.githubusercontent.com/AloisSeckar/nuxt-spec/refs/tags/v0.2.0-alpha.3/test/unit/vitest-unit.test.ts',
         'test/unit/vitest-unit.test.ts', true)
     } catch (error) {
       console.error('Error setting up \'vitest-unit.test.ts\':\n', error.message)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nuxt-spec",
-  "version": "0.2.0-alpha.2",
+  "version": "0.2.0-alpha.3",
   "description": "Test-pack layer for Nuxt Applications",
   "repository": "github:AloisSeckar/nuxt-spec",
   "license": "MIT",

package/utils/screenshot.ts

@@ -3,15 +3,21 @@ import { resolve } from 'node:path'
 import type { NuxtPage } from '@nuxt/test-utils'
 import { expect } from 'vitest'
 
-export async function compareScreenshot(page: NuxtPage, fileName: string, targetDir?: string): Promise<boolean> {
-  const dir = resolve(process.cwd(), targetDir ?? 'test/e2e')
+export async function compareScreenshot(page: NuxtPage, options?: { fileName?: string, targetDir?: string, selector?: string }): Promise<boolean> {
+  const dir = resolve(process.cwd(), options?.targetDir ?? 'test/e2e')
   const baselineDir = resolve(dir, '__baseline__')
   const currentDir = resolve(dir, '__current__')
 
-  // capture full-page screenshot as PNG
-  const screenshot = await page.screenshot({ fullPage: true })
+  const route = page.url().substring(page.url().lastIndexOf('/') + 1) || 'index'
+  const fileName = options?.fileName ?? `${route}.png`
+
+  // capture element specified by locator or a full-page screenshot as PNG
+  const screenshot = options?.selector
+    ? await page.locator(options.selector).screenshot()
+    : await page.screenshot({ fullPage: true })
   const baselinePath = resolve(baselineDir, fileName)
 
+  // @ts-expect-error - this is reliable way of reading Vitest "update" flag
   const updating = expect.getState().snapshotState?._updateSnapshot === 'all'
   if (updating || !existsSync(baselinePath)) {
     // save new baseline screenshot