@poveste/plugin-vue 0.19.1 → 0.21.0

package/src/testing/index.ts

@@ -0,0 +1,286 @@
+import type { ServerStory, ServerStoryFile, Story, StoryFile, Variant } from '@poveste/shared'
+import type { App, Component } from 'vue'
+import type { PreviewRenderContext } from '../client/app/render-context.js'
+// @ts-expect-error virtual module id
+import { environmentApp, environmentReady } from 'virtual:$poveste-testing-environment'
+import { describe, it } from 'vitest'
+import { markRaw, nextTick, reactive } from 'vue'
+import { registerControlComponents } from '../client/app/global-components.js'
+import { createPreviewHost } from '../client/app/host.js'
+import { syncStateBundledAndExternal } from '../client/app/util.js'
+import { collectComponent } from '../client/server/collect.js'
+
+export interface TestStoriesOptions {
+  /** The outer `describe`'s name. The story file's name by default. */
+  name?: string
+  /**
+   * How long a variant's setup may take to settle, in milliseconds: an
+   * `initState` or an async `setup()` still pending then fails the test.
+   */
+  timeout?: number
+}
+
+type StoryComponent = Component & { __file?: string, doc?: string }
+
+/**
+ * Turns a story file into one test per variant. Each test renders the variant
+ * the way the preview does, and fails on what the preview would only log: an
+ * error from setup or render, a rejected `initState`, or a `[Vue warn]`.
+ *
+ * ```ts
+ * import { testStories } from '@poveste/plugin-vue/testing'
+ * import BaseButton from './BaseButton.story.vue'
+ *
+ * testStories(BaseButton)
+ * ```
+ */
+export function testStories(component: StoryComponent, options: TestStoriesOptions = {}): void {
+  const name = options.name ?? fileName(component.__file) ?? 'stories'
+  const timeout = options.timeout ?? 5000
+
+  describe(name, async () => {
+    await environmentReady()
+    const { stories, problems } = await collect(component, name)
+
+    if (problems.length || !stories.length) {
+      it('collects', () => {
+        throw failure(`collecting ${name}`, problems.length ? problems : ['it has no <Story>'])
+      })
+      return
+    }
+
+    for (const story of stories) {
+      describe(story.title, () => {
+        for (const variant of story.variants) {
+          it(variant.title, async () => {
+            const found = await renderVariant(story, variant, timeout)
+            if (found.length) {
+              throw failure(`${story.title} › ${variant.title}`, found)
+            }
+          })
+        }
+      })
+    }
+  })
+}
+
+async function collect(component: StoryComponent, name: string) {
+  const path = component.__file ?? name
+  const base = fileName(path) ?? name
+  const file = {
+    id: name.replace(/\W+/g, '-').toLowerCase(),
+    path,
+    moduleId: path,
+    // As poveste names it: what a `<Story>` with no `title` is called.
+    fileName: base.includes('.') ? base.slice(0, base.indexOf('.')) : base,
+  } as ServerStoryFile
+  const storyData: ServerStory[] = []
+  const problems: unknown[] = []
+  const el = document.createElement('div')
+
+  try {
+    await collectComponent(component, { file, storyData, el }, {
+      beforeSetup(app) {
+        app.config.errorHandler = (err) => {
+          problems.push(err)
+        }
+        app.config.warnHandler = (message, _instance, trace) => {
+          problems.push(vueWarning(message, trace))
+        }
+      },
+      afterSetup(app) {
+        copyMissing(app._context.components, controlComponents())
+        inheritEnvironmentApp(app)
+      },
+    })
+  }
+  catch (err) {
+    // A setup file that throws, reported as the file's one failing test.
+    problems.push(err)
+  }
+
+  const storyFile = {
+    id: file.id,
+    supportPluginId: 'vue3',
+    component: markRaw(component),
+    path: [],
+    filePath: file.path,
+    source: async () => ({ default: '' }),
+  } as unknown as StoryFile
+
+  const stories = storyData.map((data) => {
+    const story: Story = {
+      ...data,
+      file: markRaw(storyFile),
+      variants: data.variants.map(variant => toClientVariant(variant as unknown as Variant)),
+      slots: () => ({}),
+    } as Story
+    storyFile.story = story
+    return story
+  })
+  return { stories, problems }
+}
+
+function toClientVariant(variant: Variant): Variant {
+  return {
+    ...variant,
+    state: reactive({
+      _hPropState: {},
+      _hPropDefs: {},
+    }),
+    setupApp: undefined,
+    slots: () => ({}),
+    previewReady: false,
+  }
+}
+
+/**
+ * The mount pass a sandbox runs, for the variant's `initState`, then the render
+ * pass for its default slot: what the preview shows.
+ */
+async function renderVariant(story: Story, variant: Variant, timeout: number): Promise<unknown[]> {
+  const found: unknown[] = []
+  const onError = (err: unknown) => {
+    found.push(err)
+  }
+  const onWarn = (message: string, trace: string) => {
+    found.push(vueWarning(message, trace))
+  }
+  let resolved = false
+  const el = document.createElement('div')
+  document.body.appendChild(el)
+
+  const mountHost = createPreviewHost({
+    name: 'StoryTestMount',
+    el,
+    getStory: () => story,
+    getVariant: () => null,
+    renderContext: reactive({
+      mode: 'mount',
+      slotName: 'default',
+      currentVariant: null,
+      targetVariantId: variant.id,
+      externalState: null,
+      nextVariantIndex: { value: 0 },
+    }) as PreviewRenderContext,
+    onError,
+    onWarn,
+    configureApp: inheritEnvironmentApp,
+  })
+
+  const externalState = reactive<Variant['state']>({})
+  const stateSync = syncStateBundledAndExternal(variant.state, externalState)
+  const renderHost = createPreviewHost({
+    name: 'StoryTestRender',
+    el,
+    getStory: () => story,
+    getVariant: () => variant,
+    renderContext: reactive({
+      mode: 'render',
+      slotName: 'default',
+      currentVariant: variant,
+      externalState,
+      nextVariantIndex: { value: 0 },
+    }) as PreviewRenderContext,
+    wrapInDiv: true,
+    onError,
+    onWarn,
+    onResolve: () => {
+      resolved = true
+    },
+    configureApp: inheritEnvironmentApp,
+  })
+
+  try {
+    await mountHost.mount()
+    if (!await settled(() => !!variant.configReady || found.length > 0, timeout)) {
+      found.push(new Error(`its setup did not settle within ${timeout} ms`))
+    }
+    if (!found.length) {
+      await renderHost.mount()
+      // Until its async setups settle: one that throws after an `await` is caught
+      // only once it does.
+      if (!await settled(() => resolved || found.length > 0, timeout)) {
+        found.push(new Error(`its render did not settle within ${timeout} ms`))
+      }
+    }
+  }
+  catch (err) {
+    found.push(err)
+  }
+  finally {
+    renderHost.unmount()
+    mountHost.unmount()
+    stateSync.stop()
+    el.remove()
+  }
+
+  return found
+}
+
+// The controls' globals, registered without the warning a second registration of
+// a name the book's setup file already took would print.
+function controlComponents(): Record<string, Component> {
+  const registry: Record<string, Component> = {}
+  registerControlComponents({ component: (name: string, component: Component) => {
+    registry[name] = component
+  } } as unknown as App)
+  return registry
+}
+
+/**
+ * Gives a story's app the context of the app the test environment boots, so the
+ * story's `useNuxtApp()` and the plugins' injections resolve as in `poveste dev`.
+ * What `@nuxt/test-utils`' own mounts copy.
+ */
+function inheritEnvironmentApp(app: App) {
+  const host: App | undefined = environmentApp()
+  if (!host) {
+    return
+  }
+  copyMissing(app, host)
+  copyMissing(app._context.provides, host._context.provides)
+  copyMissing(app.config.globalProperties, host.config.globalProperties)
+  copyMissing(app._context.components, host._context.components)
+  copyMissing(app._context.directives, host._context.directives)
+}
+
+// By descriptor: Nuxt defines `$nuxt` and its injections as getters that aren't
+// enumerable, so a spread or `Object.assign` leaves them behind.
+function copyMissing(target: object, source: object) {
+  for (const key of Reflect.ownKeys(source)) {
+    if (!(key in target)) {
+      Object.defineProperty(target, key, Object.getOwnPropertyDescriptor(source, key)!)
+    }
+  }
+}
+
+async function settled(done: () => boolean, timeout: number): Promise<boolean> {
+  const deadline = Date.now() + timeout
+  do {
+    await nextTick()
+    await new Promise(resolve => setTimeout(resolve))
+    if (done()) {
+      return true
+    }
+  } while (Date.now() < deadline)
+  return done()
+}
+
+function failure(where: string, found: unknown[]): Error {
+  const first = found[0]
+  const lines = found.map(item => item instanceof Error ? (item.stack ?? item.message) : String(item))
+  const error = new Error(`${where}: ${found.length === 1 ? 'one problem' : `${found.length} problems`}\n\n${lines.join('\n\n')}`)
+  if (first instanceof Error) {
+    error.cause = first
+  }
+  return error
+}
+
+function vueWarning(message: string, trace: string): string {
+  return `[Vue warn]: ${message}${trace ? `\n${trace}` : ''}`
+}
+
+function fileName(path: string | undefined): string | undefined {
+  return path?.split(/[\\/]/).pop()
+}

package/src/testing/vite.ts

@@ -0,0 +1,194 @@
+import type { PovesteConfig } from 'poveste'
+import type { Plugin, UserConfig } from 'vite'
+import { existsSync } from 'node:fs'
+import { createRequire } from 'node:module'
+import { dirname, join, relative, resolve, sep } from 'node:path'
+import { clientConfig, VIRTUAL_IDS } from '@poveste/shared'
+import { getDefaultConfig, loadConfigFile, mergeConfig, resolveConfigFile } from 'poveste'
+import { VUE_SETUP_HOOK_NAMES } from '../setup-hooks.js'
+import { projectVueVersion } from '../util/project-vue.js'
+import { VAPOR_INTEROP_ID, vaporInteropModule } from '../util/vapor.js'
+
+const EMPTY_SETUP_ID = '\0poveste-testing:empty-setup'
+const CONFIG_RESOLVED_ID = `\0${VIRTUAL_IDS.config}`
+const ENVIRONMENT_ID = 'virtual:$poveste-testing-environment'
+
+// Vitest hands what it finds in `node_modules` to Node, which can't load the
+// `virtual:` modules these packages import, so in a book that installs them no test
+// ran (#1503). The workspace links them, and Vitest inlines a linked package.
+const POVESTE_PACKAGES = [/\/node_modules\/poveste\//, /\/node_modules\/@poveste\//]
+
+const EMPTY_SETUP = VUE_SETUP_HOOK_NAMES.map(name => `export const ${name} = undefined`).join('\n')
+
+// `logEvent` from `poveste/client` reaches `@poveste/app`, which names these. A
+// test never runs the code that reads them, but Vite's dependency scan follows
+// the imports, and one it can't resolve skips pre-bundling and reloads the
+// browser run partway through.
+const INERT: Record<string, string> = {
+  [VIRTUAL_IDS.markdownFiles]: 'export const markdownFiles = []\n',
+  [VIRTUAL_IDS.componentDocs]: 'export const componentDocs = {}\n',
+  [VIRTUAL_IDS.supportPluginsClient]: 'export const clientSupportPlugins = {}\n',
+}
+
+// Nuxt boots in `@nuxt/test-utils`' `beforeAll`, after Vitest has collected the
+// tests, and a story's own setup can call a Nuxt composable while it is being
+// collected. So its own `setupNuxt` runs before collection, into the promise that
+// `beforeAll` awaits, and Nuxt boots once and in full. Both names are internal to
+// `@nuxt/test-utils`: if a version renames them, the story tests fail loudly.
+function nuxtEnvironment(setupNuxt: string) {
+  return `import { tryUseNuxtApp } from '#app/nuxt'
+import { setupNuxt } from ${JSON.stringify(setupNuxt)}
+
+export async function environmentReady() {
+  const win = window
+  if (!win.__NUXT_VITEST_ENVIRONMENT__ || tryUseNuxtApp()) {
+    return
+  }
+  win.__NUXT_VITEST_ENVIRONMENT_PROMISE__ ??= setupNuxt()
+  await win.__NUXT_VITEST_ENVIRONMENT_PROMISE__
+}
+
+export function environmentApp() {
+  return tryUseNuxtApp()?.vueApp
+}
+`
+}
+
+const NO_ENVIRONMENT = `export async function environmentReady() {}\nexport function environmentApp() {\n  return undefined\n}\n`
+
+// `@nuxt/test-utils`' own boot, by file: its `exports` don't list it.
+function setupNuxtFile(root: string): string | undefined {
+  try {
+    const file = join(dirname(createRequire(join(root, 'package.json')).resolve('@nuxt/test-utils/package.json')), 'dist/runtime/shared/nuxt.mjs')
+    return existsSync(file) ? file : undefined
+  }
+  catch {
+    return undefined
+  }
+}
+
+// Root-relative, as `poveste dev` reads it: the docs write `/src/poveste.setup.ts`,
+// which `resolve` takes as absolute, so pre-bundling scanned a file outside the
+// book and the setup file's imports were found late, with a reload (#1507).
+function setupFileOf(config: Partial<PovesteConfig>): string | undefined {
+  const setupFile = config.setupFile
+  const file = typeof setupFile === 'string' ? setupFile : setupFile && 'browser' in setupFile ? setupFile.browser : undefined
+  return file?.replace(/^\/+/, '')
+}
+
+export interface PovesteTestingOptions {
+  /** The book's poveste config file. Found from the Vite root by default. */
+  configFile?: string
+}
+
+/**
+ * What a story needs in the user's own Vitest to render as `poveste dev` renders
+ * it: the book's setup file and the modules Poveste's client imports, with
+ * Poveste's own packages inlined so Vitest can serve those, and `vue` and the
+ * setup file pre-bundled for browser mode. Nothing else: no alias and no change
+ * to how anything resolves, so the test sees the project's Vite config as the
+ * project wrote it.
+ *
+ * Setup code that a plugin generates for `poveste dev`, such as the Nuxt app
+ * `@poveste/plugin-nuxt` boots, is left to the test environment, which already
+ * provides it: `@nuxt/test-utils`'s `nuxt` environment does in a Nuxt project.
+ */
+export function povesteTesting(options: PovesteTestingOptions = {}): Plugin {
+  let root = process.cwd()
+  let config: Partial<PovesteConfig> = {}
+
+  return {
+    name: 'poveste:testing',
+
+    async config(user) {
+      root = resolve(user.root ?? process.cwd())
+      const file = options.configFile ? resolve(root, options.configFile) : resolveConfigFile(root)
+      const fromFile = file ? await loadConfigFile(file) : {}
+      // As `poveste dev` reads it: the config file, then the Vite config's key.
+      const fromVite = ((user as { poveste?: unknown, histoire?: unknown }).poveste
+        ?? (user as { histoire?: unknown }).histoire ?? {}) as Partial<PovesteConfig>
+      config = mergeConfig(fromFile, fromVite) as Partial<PovesteConfig>
+
+      // In browser mode Vite pre-bundles what its scan finds. It never sees `vue`,
+      // which compiled templates and this package's own bundle import, nor the
+      // setup file, which arrives as a virtual module. Each was bundled later,
+      // with a reload partway through the first run, and two copies of Vue
+      // failed it (#1503).
+      const setupFile = setupFileOf(config)
+      const optimizeDeps = {
+        include: ['vue'],
+        ...setupFile ? { entries: [relative(root, resolve(root, setupFile)).split(sep).join('/')] } : {},
+      }
+      // `true` already inlines everything, and an array merged into it would not.
+      if ((user as { test?: { server?: { deps?: { inline?: unknown } } } }).test?.server?.deps?.inline === true) {
+        return { optimizeDeps }
+      }
+      return { optimizeDeps, test: { server: { deps: { inline: POVESTE_PACKAGES } } } } as UserConfig
+    },
+
+    configResolved(resolved) {
+      root = resolved.root
+    },
+
+    async resolveId(id, importer) {
+      if (id === VIRTUAL_IDS.setup) {
+        const file = setupFileOf(config)
+        if (file) {
+          return this.resolve(resolve(root, file), importer, { skipSelf: true })
+        }
+        return EMPTY_SETUP_ID
+      }
+      if (id === VIRTUAL_IDS.generatedGlobalSetup) {
+        return EMPTY_SETUP_ID
+      }
+      if (id === VIRTUAL_IDS.config) {
+        return CONFIG_RESOLVED_ID
+      }
+      if (id === VAPOR_INTEROP_ID) {
+        return `\0${VAPOR_INTEROP_ID}`
+      }
+      if (Object.hasOwn(INERT, id)) {
+        return `\0${id}`
+      }
+      if (id === ENVIRONMENT_ID) {
+        return `\0${ENVIRONMENT_ID}`
+      }
+      return undefined
+    },
+
+    // A story's `<docs>` block, which `poveste dev` renders as markdown. A test
+    // renders the variants, not the docs, so it only has to import.
+    transform(_code, id) {
+      if (id.includes('?vue&type=docs')) {
+        return 'export default () => {}'
+      }
+      return undefined
+    },
+
+    async load(id) {
+      if (id === EMPTY_SETUP_ID) {
+        return EMPTY_SETUP
+      }
+      if (id === CONFIG_RESOLVED_ID) {
+        return `export const config = ${JSON.stringify(clientConfig({ ...getDefaultConfig(), ...config }))}\nexport const logos = {}\n`
+      }
+      if (id === `\0${VAPOR_INTEROP_ID}`) {
+        return vaporInteropModule(projectVueVersion(root))
+      }
+      if (id.startsWith('\0') && Object.hasOwn(INERT, id.slice(1))) {
+        return INERT[id.slice(1)]
+      }
+      // The app the test environment boots: Nuxt's, under `@nuxt/test-utils`' `nuxt`
+      // environment. `poveste dev` renders a story inside the Nuxt app its plugin
+      // boots, and a test does the same. Told by Nuxt's own `#app` alias and the
+      // test utils being installed, not by `#imports`, which unimport also serves.
+      if (id === `\0${ENVIRONMENT_ID}`) {
+        const setupNuxt = setupNuxtFile(root)
+        return setupNuxt && await this.resolve('#app/nuxt', resolve(root, 'index.html'))
+          ? nuxtEnvironment(setupNuxt)
+          : NO_ENVIRONMENT
+      }
+      return undefined
+    },
+  }
+}

package/src/util/project-vue.ts

@@ -0,0 +1,13 @@
+import { readFileSync } from 'node:fs'
+import { createRequire } from 'node:module'
+import { join } from 'node:path'
+
+export function projectVueVersion(root: string): string | undefined {
+  try {
+    const manifest = createRequire(join(root, 'package.json')).resolve('vue/package.json')
+    return JSON.parse(readFileSync(manifest, 'utf8')).version
+  }
+  catch {
+    return undefined
+  }
+}

package/src/util/vue-plugin.ts

@@ -0,0 +1,32 @@
+import type { Plugin as VitePlugin } from 'vite'
+import { existsSync } from 'node:fs'
+import { join } from 'node:path'
+
+const QUASAR_CONFIGS = ['quasar.config.js', 'quasar.config.mjs', 'quasar.config.cjs', 'quasar.config.ts']
+
+/**
+ * What to say when a book's Vite config has no Vue plugin. Without one, Vite
+ * answers the first `.vue` file with "Install @vitejs/plugin-vue", which sends a
+ * Quasar reader to install a package their project does not need: Quasar brings
+ * its own Vue plugin, and `HstQuasar()` is what hands it to Poveste (#1337).
+ */
+export function noVuePluginMessage(root: string, exists: (path: string) => boolean = existsSync): string {
+  const fix = QUASAR_CONFIGS.some(name => exists(join(root, name)))
+    ? 'This is a Quasar project: add `HstQuasar()` from `@poveste/plugin-quasar` to the config\'s `plugins`, which brings Quasar\'s own Vue plugin.'
+    : 'Add `@vitejs/plugin-vue` to `vite.config`, or in a Nuxt project `HstNuxt()` from `@poveste/plugin-nuxt` to the config\'s `plugins`.'
+  return `[poveste] The Vite config has no Vue plugin, so no \`.vue\` story can be compiled. ${fix}`
+}
+
+/** Reports, once per process, a resolved Vite config with no Vue plugin in it. */
+export function requireVuePlugin(): VitePlugin {
+  let reported = false
+  return {
+    name: 'poveste-plugin-vue:require-vue-plugin',
+    configResolved(config) {
+      if (!reported && !config.plugins.some(plugin => plugin.name === 'vite:vue')) {
+        reported = true
+        console.error(noVuePluginMessage(config.root))
+      }
+    },
+  }
+}

package/testing.d.ts

@@ -0,0 +1,2 @@
+// https://github.com/microsoft/TypeScript/issues/33079
+export * from './dist/testing/index'