test: assert on rendered terminal output with ansivision

Author: danielroe

package.json

@@ -28,6 +28,7 @@
     "@nuxt/test-utils": "^4.0.3",
     "@types/node": "^24.13.3",
     "@vitest/coverage-v8": "^4.1.10",
+    "ansivision": "^0.4.0",
     "changelogen": "^0.6.2",
     "eslint": "^10.7.0",
     "exsolve": "^1.1.0",

packages/nuxt-cli/test/unit/terminal-output.spec.ts

@@ -0,0 +1,206 @@
+import type { Renderer } from 'ansivision'
+import type { Listener } from '../../src/dev/listen'
+import type { ShortcutContext } from '../../src/dev/shortcuts'
+
+import { PassThrough } from 'node:stream'
+
+import { afterEach, describe, expect, it, vi } from 'vitest'
+
+import { colourOf, render, screen as visibleScreen } from '../utils/terminal'
+
+// Colours have to be forced before `picocolors` is imported, so the modules
+// under test are loaded dynamically below.
+process.env.FORCE_COLOR = '3'
+
+vi.mock('std-env', () => ({ isCI: false, isTest: false }))
+
+const { listen, openBrowser, printQRCode } = await import('../../src/dev/listen')
+const { setupShortcuts } = await import('../../src/dev/shortcuts')
+
+/** SGR foreground colour indexes, as reported by `ansivision`. */
+const GREEN = 2
+const MAGENTA = 5
+const CYAN = 6
+
+/** The visible screen, with ports and QR codes replaced by stable markers. */
+function screen(renderer: Renderer): string {
+  return visibleScreen(renderer)
+    .replaceAll(/:\d{4,5}\b/g, ':<port>')
+    .replaceAll(/[\u2580-\u259F]+/g, '<qr>')
+}
+
+/** Pretend to be a Linux desktop running `browser`, or a headless one. */
+function stubDisplay({ browser }: { browser?: string } = {}): () => void {
+  const platform = process.platform
+  const env = { ...process.env }
+  Object.defineProperty(process, 'platform', { value: 'linux', configurable: true })
+  process.env = {
+    ...env,
+    DISPLAY: browser ? ':0' : undefined,
+    WAYLAND_DISPLAY: undefined,
+    WSL_DISTRO_NAME: undefined,
+    BROWSER: browser,
+  }
+  return () => {
+    Object.defineProperty(process, 'platform', { value: platform, configurable: true })
+    process.env = env
+  }
+}
+
+describe('dev server terminal output', () => {
+  const listeners: Listener[] = []
+
+  afterEach(async () => {
+    await Promise.all(listeners.splice(0).map(listener => listener.close()))
+    vi.restoreAllMocks()
+  })
+
+  async function start(options: Parameters<typeof listen>[1] = {}) {
+    const listener = await listen((_req, res) => res.end('ok'), { port: 0, qr: false, ...options })
+    listeners.push(listener)
+    return listener
+  }
+
+  async function withShortcuts(context: Partial<ShortcutContext> = {}) {
+    const stdin = new PassThrough() as unknown as typeof process.stdin
+    Object.assign(stdin, { isTTY: true })
+    vi.spyOn(process, 'stdin', 'get').mockReturnValue(stdin)
+
+    const listener = await start({ showURL: false })
+    setupShortcuts({
+      listener,
+      close: async () => {},
+      onReady: callback => callback(listener.url),
+      ...context,
+    })
+
+    return {
+      listener,
+      press: async (input: string) => {
+        stdin.write(`${input}\n`)
+        await new Promise(resolve => setImmediate(resolve))
+      },
+    }
+  }
+
+  describe('startup', () => {
+    it('should print the url block', async () => {
+      const renderer = await render(() => start())
+
+      expect(screen(renderer)).toMatchInlineSnapshot(`
+        "  ➜ Local:    http://localhost:<port>/
+          ➜ Network:  use --host to expose"
+      `)
+    })
+
+    it('should colour each url type differently', async () => {
+      const renderer = await render(() => start())
+      renderer.goToFrame(renderer.frames.length - 1)
+
+      expect(renderer.currentStyledFrame).toContain('\u001B[')
+      expect(colourOf(renderer, 'Local:')).toBe(GREEN)
+      expect(colourOf(renderer, 'Network:')).toBe(MAGENTA)
+      expect(colourOf(renderer, 'http://localhost')).toBe(CYAN)
+    })
+
+    it('should flag which url the qr code points at', async () => {
+      const renderer = await render(() => start({ qr: true, publicURL: 'https://example.com/' }))
+
+      expect(screen(renderer)).toContain('<qr>')
+      expect(screen(renderer)).toContain('https://example.com/ [QR code]')
+    })
+
+    it('should not caption the qr code, which the url block already labels', async () => {
+      const renderer = await render(() => start({ qr: true }))
+
+      expect(screen(renderer)).not.toMatch(/<qr>\n\s+http/)
+    })
+  })
+
+  describe('shortcuts', () => {
+    it('should caption a standalone qr code with its url', async () => {
+      const renderer = await render(() => printQRCode('http://192.168.1.20:3000/', { showURL: true }))
+      const lines = screen(renderer).split('\n').filter(Boolean)
+
+      expect(lines.at(-1)).toContain('http://192.168.1.20:<port>/')
+      // The caption is centred under the code rather than flush left.
+      expect(lines.at(-1)!.startsWith(' ')).toBe(true)
+    })
+
+    it('should leave only the url block on screen after clearing', async () => {
+      const { press } = await withShortcuts()
+
+      const renderer = await render(async () => {
+        // eslint-disable-next-line no-console
+        console.log('noise from a previous build')
+        await press('clear')
+      })
+
+      expect(screen(renderer)).toMatchInlineSnapshot(`
+        "  ➜ Local:    http://localhost:<port>/
+          ➜ Network:  use --host to expose"
+      `)
+      expect(renderer.frames.at(-1)).not.toContain('noise from a previous build')
+    })
+
+    it('should list the available shortcuts', async () => {
+      const { press } = await withShortcuts()
+
+      const renderer = await render(() => press('h'))
+
+      expect(screen(renderer)).toMatchInlineSnapshot(`
+        "  press o + enter to open in browser
+          press u + enter to show server URLs
+          press qr + enter to show a QR code for the server URL
+          press copy + enter to copy the server URL to the clipboard
+          press c + enter to clear the console
+          press q + enter to quit
+          press h + enter to show this help"
+      `)
+    })
+
+    it('should list restart first when a restart handler is available', async () => {
+      const { press } = await withShortcuts({ restart: () => {} })
+
+      const renderer = await render(() => press('h'))
+
+      expect(screen(renderer).split('\n')[0]).toContain('press r + enter to restart the dev server')
+    })
+  })
+
+  describe('browser launch', () => {
+    it('should say so when the browser launcher fails', async () => {
+      const restore = stubDisplay({ browser: '/definitely/not/a/launcher' })
+
+      const renderer = await render(async ({ waitForOutput }) => {
+        openBrowser('http://localhost:3000/')
+        await waitForOutput('Could not open')
+      })
+      restore()
+
+      expect(screen(renderer)).toContain('Could not open http://localhost:<port>/ in a browser.')
+    })
+
+    it('should say so when the browser launcher exits with an error', async () => {
+      const restore = stubDisplay({ browser: 'false' })
+
+      const renderer = await render(async ({ waitForOutput }) => {
+        openBrowser('http://localhost:3000/')
+        await waitForOutput('Could not open')
+      })
+      restore()
+
+      expect(screen(renderer)).toContain('Could not open http://localhost:<port>/ in a browser.')
+    })
+
+    it('should say so when there is no browser to open', async () => {
+      const restore = stubDisplay()
+      const { press } = await withShortcuts()
+
+      const renderer = await render(() => press('o'))
+      restore()
+
+      expect(screen(renderer)).toContain('No browser is available in this environment. Open http://localhost:<port>/ manually.')
+    })
+  })
+})

packages/nuxt-cli/test/unit/utils/banner.spec.ts

@@ -1,5 +1,20 @@
+import type { Nuxt } from '@nuxt/schema'
+
 import { describe, expect, it, vi } from 'vitest'
 
+import { render, screen } from '../../utils/terminal'
+
+// Colours have to be forced before `picocolors` is imported by the module under test.
+process.env.FORCE_COLOR = '3'
+
+const VERSIONS: Record<string, string> = {
+  'webpack': '5.99.0',
+  '@rspack/core': '1.3.0',
+  'nuxt': '4.4.6',
+  'nitropack': '2.13.4',
+  'vue': '3.5.39',
+}
+
 vi.mock('../../../src/utils/versions', () => ({
   getPkgJSON: vi.fn((_cwd: string, pkg: string, options?: { via?: string[] }) => {
     if (pkg === 'vite' && options?.via?.includes('@nuxt/vite-builder')) {
@@ -8,17 +23,17 @@ vi.mock('../../../src/utils/versions', () => ({
     return null
   }),
   getPkgVersion: vi.fn((_cwd: string, pkg: string, options?: { via?: string[] }) => {
-    if (pkg === 'webpack' && options?.via?.includes('@nuxt/webpack-builder')) {
-      return '5.99.0'
+    if (pkg === 'webpack' && !options?.via?.includes('@nuxt/webpack-builder')) {
+      return ''
     }
-    if (pkg === '@rspack/core' && options?.via?.includes('@nuxt/rspack-builder')) {
-      return '1.3.0'
+    if (pkg === '@rspack/core' && !options?.via?.includes('@nuxt/rspack-builder')) {
+      return ''
     }
-    return ''
+    return VERSIONS[pkg] || ''
   }),
 }))
 
-const { getBuilder } = await import('../../../src/utils/banner')
+const { getBuilder, showBanner } = await import('../../../src/utils/banner')
 
 describe('getBuilder', () => {
   it('resolves vite version via nuxt -> @nuxt/vite-builder', () => {
@@ -33,3 +48,15 @@ describe('getBuilder', () => {
     expect(getBuilder('/any', 'rspack')).toEqual({ name: 'Rspack', version: '1.3.0' })
   })
 })
+
+describe('showBanner', () => {
+  it('should print every version on one line', async () => {
+    const renderer = await render(() =>
+      showBanner({ _version: '4.4.6', options: { rootDir: '/any', builder: 'vite' } } as unknown as Nuxt))
+
+    expect(screen(renderer)).toMatchInlineSnapshot(`
+      "│
+      ●  Nuxt 4.4.6 (with Nitro 2.13.4, Vite 7.3.1 and Vue 3.5.39)"
+    `)
+  })
+})

packages/nuxt-cli/test/utils/terminal.ts

@@ -0,0 +1,71 @@
+import type { Renderer } from 'ansivision'
+
+import process from 'node:process'
+
+import { RenderStream } from 'ansivision'
+import { vi } from 'vitest'
+
+export interface RenderContext {
+  /** Wait for `matcher` to show up in the output, for asynchronous logs. */
+  waitForOutput: (matcher: string | RegExp) => Promise<void>
+}
+
+/**
+ * Replay everything written to the terminal through a virtual one, so tests can
+ * assert on what a user would see rather than on raw escape sequences.
+ *
+ * Both sinks feed the same stream so escape sequences stay ordered relative to
+ * the logs; `console.log` cannot be left to `process.stdout` because vitest
+ * replaces the global console.
+ */
+export async function render(run: (context: RenderContext) => unknown): Promise<Renderer> {
+  const stream = new RenderStream()
+  let output = ''
+  const capture = (chunk: string) => {
+    output += chunk
+    stream.write(chunk)
+  }
+
+  const log = vi.spyOn(console, 'log').mockImplementation((...args: unknown[]) => capture(`${args.join(' ')}\n`))
+  const write = vi.spyOn(process.stdout, 'write').mockImplementation((chunk: unknown) => {
+    capture(chunk as string)
+    return true
+  })
+
+  try {
+    await run({
+      waitForOutput: matcher => vi.waitFor(() => {
+        if (!output.match(matcher)) {
+          throw new Error(`Timed out waiting for ${matcher} in terminal output`)
+        }
+      }),
+    })
+  }
+  finally {
+    log.mockRestore()
+    write.mockRestore()
+  }
+
+  // The renderer only catches up once the stream has drained.
+  await new Promise<void>(resolve => stream.end(resolve))
+  return stream.renderer
+}
+
+/**
+ * The visible screen. `ansivision` starts a new frame whenever the screen is
+ * cleared, so the last frame is what is on screen now.
+ */
+export function screen(renderer: Renderer): string {
+  return (renderer.frames.at(-1) ?? '')
+    .split('\n')
+    .map(line => line.trimEnd())
+    .join('\n')
+    .replaceAll(/^\n+|\n+$/g, '')
+}
+
+/** Foreground colour of the first character of `text` on screen. */
+export function colourOf(renderer: Renderer, text: string): unknown {
+  const lines = (renderer.frames.at(-1) ?? '').split('\n')
+  const row = lines.findIndex(line => line.includes(text))
+  return renderer.getStyleAtPosition(row, lines[row]!.indexOf(text)).foreground
+}