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

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.1"
+"nuxt-spec": "0.2.0-alpha.2"
 ```
 
 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.1/test).
+You can use sample files from the [project repository](https://github.com/AloisSeckar/nuxt-spec/tree/v0.2.0-alpha.2/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.1/CHANGELOG.md) for the latest updates and features.
+See [CHANGELOG.md](https://github.com/AloisSeckar/nuxt-spec/blob/v0.2.0-alpha.2/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.1/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.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.
 
 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:
 
@@ -307,19 +307,19 @@ Nuxt Spec offers couple of utility functions that are exported via `nuxt-spec/ut
 You can use them in your test files as follows:
 
 ```ts
-import { compareScrenshot, gotoPage, getDataHtml, getAPIResultHtml, } from 'nuxt-spec/utils'
+import { compareScreenshot, gotoPage, getDataHtml, getAPIResultHtml, } from 'nuxt-spec/utils'
 
 // accepts instance of NuxtPage (from @nuxt/test-utils)
 // 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 compareScrenshot(page, 'screenshot.png')
+await compareScreenshot(page, 'screenshot.png')
 
 // navigates to given URL and returns the instance of NuxtPage (from @nuxt/test-utils)
 const page: NuxtPage = await gotoPage('url')
 
 // accepts either a URL string or instance of NuxtPage (from @nuxt/test-utils) and a CSS selector
-// returns innerHTML of the element matching the selector
+// returns `innerHTML` of the element matching the selector
 const html: string = await getDataHtml('/', '#test') 
 const html: string = await getDataHtml(page, '#test')
 
@@ -327,12 +327,13 @@ const html: string = await getDataHtml(page, '#test')
 // css selector for element that triggers API call when clicked (i.e. button)
 // fragment of API endpoint URL that should be called (to test the response)
 // css selector for element where the API response should be rendered (i.e. div)
-// returns innerHTML of the element matching the result selector after the API call is made by Playwright runner
-const html: string = await getAPIResultHtml('/', '#api-fetch', 'jsonplaceholder.typicode.com/posts', '#api-result')
-const html: string = await getAPIResultHtml(page, '#api-fetch', 'jsonplaceholder.typicode.com/posts', '#api-result')
+// returns `innerHTML` of the element matching the result selector after the API call 
+// is made by Playwright runner
+const html: string = await getAPIResultHtml('/', '#api-fetch', '/your-api', '#api-result')
+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.1/utils/index.d.ts).
+For detailed description, see [utils.d.ts](https://github.com/AloisSeckar/nuxt-spec/blob/v0.2.0-alpha.2/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.1',
+      'nuxt-spec': '0.2.0-alpha.2',
     }, 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.1/.npmrc',
+        await createFileFromWebTemplate('https://raw.githubusercontent.com/AloisSeckar/nuxt-spec/refs/tags/v0.2.0-alpha.2/.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.1/config/vitest.config.ts.template',
+    await createFileFromWebTemplate('https://raw.githubusercontent.com/AloisSeckar/nuxt-spec/refs/tags/v0.2.0-alpha.2/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.1/test/browser/vitest-browser.test.ts',
+      await createFileFromWebTemplate('https://raw.githubusercontent.com/AloisSeckar/nuxt-spec/refs/tags/v0.2.0-alpha.2/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.1/test/e2e/nuxt-e2e.test.ts',
+      await createFileFromWebTemplate('https://raw.githubusercontent.com/AloisSeckar/nuxt-spec/refs/tags/v0.2.0-alpha.2/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.1/test/e2e/nuxt-visual.test.ts',
+      await createFileFromWebTemplate('https://raw.githubusercontent.com/AloisSeckar/nuxt-spec/refs/tags/v0.2.0-alpha.2/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.1/test/nuxt/nuxt-unit.test.ts',
+      await createFileFromWebTemplate('https://raw.githubusercontent.com/AloisSeckar/nuxt-spec/refs/tags/v0.2.0-alpha.2/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.1/test/unit/vitest-unit.test.ts',
+      await createFileFromWebTemplate('https://raw.githubusercontent.com/AloisSeckar/nuxt-spec/refs/tags/v0.2.0-alpha.2/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/config/index.mjs

@@ -2,7 +2,7 @@
 // based on https://nuxt.com/docs/4.x/getting-started/testing#setup
 // `projects=false` can be used to suspend the default usage of "projects" in Vitest config
 
-import { mergeConfig } from './merge' // defu-based merge function
+import { mergeConfig } from './merge.js' // defu-based merge function
 import { defineConfig } from 'vitest/config'
 import { defineVitestProject } from '@nuxt/test-utils/config'
 import { playwright } from '@vitest/browser-playwright'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nuxt-spec",
-  "version": "0.2.0-alpha.1",
+  "version": "0.2.0-alpha.2",
   "description": "Test-pack layer for Nuxt Applications",
   "repository": "github:AloisSeckar/nuxt-spec",
   "license": "MIT",
@@ -26,7 +26,8 @@
     "app",
     "bin",
     "config",
-    "public"
+    "public",
+    "utils"
   ],
   "dependencies": {
     "@nuxt/eslint": "1.15.1",

package/utils/e2e.ts

@@ -0,0 +1,30 @@
+import { createPage, url } from '@nuxt/test-utils/e2e'
+import type { NuxtPage } from '@nuxt/test-utils'
+
+// visit a specified URL and return the page instance for further interaction
+export async function gotoPage(pageName: string): Promise<NuxtPage> {
+  const page = await createPage()
+  const urlPath = pageName.startsWith('/') ? url(pageName) : url(`/${pageName}`)
+  await page.goto(urlPath, { waitUntil: 'hydration' })
+  return page
+}
+
+// extract HTML content from specified element on a given page
+export async function getDataHtml(page: NuxtPage | string, element: string): Promise<string> {
+  const pageInstance = typeof page === 'string' ? await gotoPage(page) : page
+  const dataDiv = pageInstance.locator(element)
+  return await dataDiv.innerHTML()
+}
+
+// execute an API call and extract HTML content from the result
+// (assumes clickable element that triggers the request
+// and separate element for displaying the response)
+export async function getAPIResultHtml(page: NuxtPage | string, triggerElement: string, targetUrl: string, responseElement: string) {
+  const pageInstance = typeof page === 'string' ? await gotoPage(page) : page
+  await pageInstance.click(triggerElement)
+  await pageInstance.waitForResponse(response =>
+    response.url().includes(targetUrl) && response.ok(),
+  )
+  const resultDiv = pageInstance.locator(responseElement)
+  return await resultDiv.innerHTML()
+}

package/utils/index.d.ts

@@ -0,0 +1,53 @@
+import type { NuxtPage } from '@nuxt/test-utils'
+
+/**
+ * Visit a specified URL and return the page instance for further interaction.
+ *
+ * @param pageName - Path segment appended to the base URL (e.g. `'about'` → `/<about>`)
+ * @returns Playwright page instance after navigation and hydration
+ */
+export declare function gotoPage(pageName: string): Promise<NuxtPage>
+
+/**
+ * Extract inner HTML content from a specified element on a given page.
+ *
+ * @param page - Playwright page instance, or a page name string (will call `gotoPage` internally)
+ * @param element - CSS selector identifying the target element
+ * @returns The inner HTML of the matched element
+ */
+export declare function getDataHtml(page: NuxtPage | string, element: string): Promise<string>
+
+/**
+ * Execute an API call by clicking a trigger element, wait for a successful
+ * response matching the target URL, then extract the inner HTML from the
+ * response element.
+ *
+ * @param page - Playwright page instance, or a page name string (will call `gotoPage` internally)
+ * @param triggerElement - CSS selector for the clickable element that triggers the API request
+ * @param targetUrl - Substring matched against the response URL to identify the expected API call
+ * @param responseElement - CSS selector for the element displaying the API response
+ * @returns The inner HTML of the response element
+ */
+export declare function getAPIResultHtml(
+  page: NuxtPage | string,
+  triggerElement: string,
+  targetUrl: string,
+  responseElement: string,
+): Promise<string>
+
+/**
+ * Capture a full-page screenshot and compare it against a stored baseline PNG.
+ * When run with `-u` / `--update`, or when no baseline exists yet, the current
+ * screenshot is saved as the new baseline.
+ *
+ * @param page - Playwright page instance obtained from `createPage()`
+ * @param fileName - Name of the PNG file used for baseline storage and comparison
+ * @param targetDir - Directory for baseline/current screenshots, relative to project root (defaults to `test/e2e`)
+ * @returns `true` when the screenshot matches the baseline (or a new baseline was saved)
+ * @throws Fails the current Vitest test when a mismatch is detected
+ */
+export declare function compareScreenshot(
+  page: NuxtPage,
+  fileName: string,
+  targetDir?: string,
+): Promise<boolean>

package/utils/index.ts

@@ -0,0 +1,9 @@
+import { gotoPage, getDataHtml, getAPIResultHtml } from './e2e'
+import { compareScreenshot } from './screenshot'
+
+export {
+  compareScreenshot,
+  gotoPage,
+  getDataHtml,
+  getAPIResultHtml,
+}

package/utils/screenshot.ts

@@ -0,0 +1,34 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+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')
+  const baselineDir = resolve(dir, '__baseline__')
+  const currentDir = resolve(dir, '__current__')
+
+  // capture full-page screenshot as PNG
+  const screenshot = await page.screenshot({ fullPage: true })
+  const baselinePath = resolve(baselineDir, fileName)
+
+  const updating = expect.getState().snapshotState?._updateSnapshot === 'all'
+  if (updating || !existsSync(baselinePath)) {
+    // save new baseline screenshot
+    mkdirSync(baselineDir, { recursive: true })
+    writeFileSync(baselinePath, screenshot)
+    return true
+  }
+
+  // compare against stored baseline PNG
+  const baseline = readFileSync(baselinePath)
+  if (!screenshot.equals(baseline)) {
+    // save what the test actually saw for debugging
+    mkdirSync(currentDir, { recursive: true })
+    const actualPath = resolve(currentDir, fileName)
+    writeFileSync(actualPath, screenshot)
+    expect.fail(`Screenshot mismatch. Actual result saved to: ${actualPath}`)
+  }
+
+  return true
+}