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 @@
+importtype{Renderer}from'ansivision'
+importtype{Listener}from'../../src/dev/listen'
+importtype{ShortcutContext}from'../../src/dev/shortcuts'
+
+import{PassThrough}from'node:stream'
+
+import{afterEach,describe,expect,it,vi}from'vitest'
+
+import{colourOf,render,screenasvisibleScreen}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 }=awaitimport('../../src/dev/listen')
+const{ setupShortcuts }=awaitimport('../../src/dev/shortcuts')
+
+/** SGR foreground colour indexes, as reported by `ansivision`. */
+constGREEN=2
+constMAGENTA=5
+constCYAN=6
+
+/** The visible screen, with ports and QR codes replaced by stable markers. */
+functionscreen(renderer: Renderer): string{
+returnvisibleScreen(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. */
+functionstubDisplay({ browser }: {browser?: string}={}): ()=>void{
+constplatform=process.platform
+constenv={ ...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',()=>{
+constlisteners: Listener[]=[]
+
+afterEach(async()=>{
+awaitPromise.all(listeners.splice(0).map(listener=>listener.close()))
+vi.restoreAllMocks()
+})
+
+asyncfunctionstart(options: Parameters<typeoflisten>[1]={}){
+constlistener=awaitlisten((_req,res)=>res.end('ok'),{port: 0,qr: false, ...options})
+listeners.push(listener)
+returnlistener
+}
+
+asyncfunctionwithShortcuts(context: Partial<ShortcutContext>={}){
+conststdin=newPassThrough()asunknownastypeofprocess.stdin
+Object.assign(stdin,{isTTY: true})
+vi.spyOn(process,'stdin','get').mockReturnValue(stdin)
+
+constlistener=awaitstart({showURL: false})
+setupShortcuts({
+ listener,
+close: async()=>{},
+onReady: callback=>callback(listener.url),
+ ...context,
+})
+
+return{
+ listener,
+press: async(input: string)=>{
+stdin.write(`${input}\n`)
+awaitnewPromise(resolve=>setImmediate(resolve))
+},
+}
+}
+
+describe('startup',()=>{
+it('should print the url block',async()=>{
+constrenderer=awaitrender(()=>start())
+
+expect(screen(renderer)).toMatchInlineSnapshot(`
+ " ➜ Local: http://localhost:<port>/
+ ➜ Network: use --host to expose"
+ `)
+})
+
+it('should colour each url type differently',async()=>{
+constrenderer=awaitrender(()=>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()=>{
+constrenderer=awaitrender(()=>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()=>{
+constrenderer=awaitrender(()=>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()=>{
+constrenderer=awaitrender(()=>printQRCode('http://192.168.1.20:3000/',{showURL: true}))
+constlines=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 }=awaitwithShortcuts()
+
+constrenderer=awaitrender(async()=>{
+// eslint-disable-next-line no-console
+console.log('noise from a previous build')
+awaitpress('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 }=awaitwithShortcuts()
+
+constrenderer=awaitrender(()=>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 }=awaitwithShortcuts({restart: ()=>{}})
+
+constrenderer=awaitrender(()=>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()=>{
+constrestore=stubDisplay({browser: '/definitely/not/a/launcher'})
+
+constrenderer=awaitrender(async({ waitForOutput })=>{
+openBrowser('http://localhost:3000/')
+awaitwaitForOutput('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()=>{
+constrestore=stubDisplay({browser: 'false'})
+
+constrenderer=awaitrender(async({ waitForOutput })=>{
+openBrowser('http://localhost:3000/')
+awaitwaitForOutput('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()=>{
+constrestore=stubDisplay()
+const{ press }=awaitwithShortcuts()
+
+constrenderer=awaitrender(()=>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 @@
+importtype{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'
+
+constVERSIONS: 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', () => ({
 returnnull
 }),
 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''
+returnVERSIONS[pkg]||''
 }),
 }))
 
-const{ getBuilder }=awaitimport('../../../src/utils/banner')
+const{ getBuilder, showBanner}=awaitimport('../../../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()=>{
+constrenderer=awaitrender(()=>
+showBanner({_version: '4.4.6',options: {rootDir: '/any',builder: 'vite'}}asunknownasNuxt))
+
+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 @@
+importtype{Renderer}from'ansivision'
+
+importprocessfrom'node:process'
+
+import{RenderStream}from'ansivision'
+import{vi}from'vitest'
+
+exportinterfaceRenderContext{
+/** 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.
+ */
+exportasyncfunctionrender(run: (context: RenderContext)=>unknown): Promise<Renderer>{
+conststream=newRenderStream()
+letoutput=''
+constcapture=(chunk: string)=>{
+output+=chunk
+stream.write(chunk)
+}
+
+constlog=vi.spyOn(console,'log').mockImplementation((...args: unknown[])=>capture(`${args.join(' ')}\n`))
+constwrite=vi.spyOn(process.stdout,'write').mockImplementation((chunk: unknown)=>{
+capture(chunkasstring)
+returntrue
+})
+
+try{
+awaitrun({
+waitForOutput: matcher=>vi.waitFor(()=>{
+if(!output.match(matcher)){
+thrownewError(`Timed out waiting for ${matcher} in terminal output`)
+}
+}),
+})
+}
+finally{
+log.mockRestore()
+write.mockRestore()
+}
+
+// The renderer only catches up once the stream has drained.
+awaitnewPromise<void>(resolve=>stream.end(resolve))
+returnstream.renderer
+}
+
+/**
+ * The visible screen. `ansivision` starts a new frame whenever the screen is
+ * cleared, so the last frame is what is on screen now.
+ */
+exportfunctionscreen(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. */
+exportfunctioncolourOf(renderer: Renderer,text: string): unknown{
+constlines=(renderer.frames.at(-1)??'').split('\n')
+constrow=lines.findIndex(line=>line.includes(text))
+returnrenderer.getStyleAtPosition(row,lines[row]!.indexOf(text)).foreground
+}