fix visual regression tests

packages/kitbook/package.json

@@ -78,6 +78,7 @@
     "check:watch": "svelte-check --tsconfig ./jsconfig.json --threshold warning --diagnostic-sources js,svelte --watch",
     "test": "vitest",
     "test:components": "playwright test kitbook",
+    "playwright-install": "playwright install --with-deps",
     "test:components:update": "playwright test kitbook --update-snapshots"
   },
   "svelte": "./dist/index.js",

packages/kitbook/src/docs/9-maintainer-notes/0-roadmap.md

@@ -5,17 +5,16 @@ The API is stable and so the project is in **beta**. You can use this in product
 **Please feel free to [create an issue](https://github.com/jacob-8/kitbook/issues/new) and discuss what you may be able to contribute!**
 
 ## Before Svelte Summit
-- Fix visual-regression testing of variants 
-
+- improve viewer's component tree when components from packages are used which have slots
 - Viewer displays variants (fix variantIndex)
 - document-in-picture
 - create variant from current state
-- improve: viewer's component tree when components from packages are used which have slots
 - Kitbook Viewer trigger interface same as Svelte Inspector
 - cut release, explaining breaking change with Variants type
 - record
 
 ## Next Up
+- add page variants component reference broken
 - update templates to detect props
 - handle variant type when there are no component props
 - html snapshot regression via Vitest+happydom which stores baseline and comparisons in a single file in the static folder on build

packages/kitbook/src/lib/layout/parseModules/convertDeprecatedToCurrentApi.ts

@@ -15,8 +15,17 @@ export function convertDeprecatedVariantsToCurrentApi(module: VariantsModule | D
     },
   }
 
+  let no_name_index = 0
+
   module.variants.forEach((variant) => {
-    const variantKey = variant.name?.replaceAll(' ', '_') || 'No_Name'
+    let variantKey: string
+    if (variant.name) {
+      variantKey = variant.name.replaceAll(' ', '_')
+    }
+    else {
+      variantKey = `No_Name_${no_name_index}`
+      no_name_index++
+    }
     const variantData: Variant<any> = {
       ...variant.props,
       _meta: {
@@ -108,7 +117,7 @@ if (import.meta.vitest) {
           kitbookPath: '',
           activePath: '/foo',
         },
-        No_Name: {
+        No_Name_0: {
           kitbookPath: '',
           activePath: '/index',
           _meta: {

packages/kitbook/src/lib/layout/sidebar/search/SearchModal.variants.ts

@@ -1,15 +1,16 @@
 import type { Variant } from 'kitbook'
 import type Component from './SearchModal.svelte'
 
-export const variants: Variant<Component>[] = [
-  {
-    description: 'urls should start with `/search` since that is passed in as the kitbookPath',
-    props: {
-      kitbookPath: '/search',
+export const Basic: Variant<Component> = {
+  _meta: {
+    description: 'Hit Ctrl+K or Meta+K to open modal. Urls should start with `/search` since that is passed in as the kitbookPath',
+    tests: {
+      skip: true,
     },
     viewports: [
       { name: 'Desktop', width: 800, height: 600 },
       { name: 'Mobile', width: 320, height: 600 },
     ],
   },
-]
+  kitbookPath: '/search',
+}

packages/kitbook/src/lib/pages/MainPage.svelte

@@ -113,7 +113,7 @@
 
               <Button onclick={addComposition} form="menu" color="black"><span class="i-carbon-chart-treemap text-lg align--4px" /> Add Composition</Button>
 
-              {#if !variantsModule?.variants}
+              {#if !variantsModule}
                 <Button onclick={() => openVariants(`${pathWithoutExtension}.svelte`)} form="menu" color="black"><span class="i-system-uicons-versions align--4px text-xl" /> Add Variant</Button>
               {/if}
             {/if}

packages/kitbook/src/lib/routes/[...file]/_page.variants.ts

@@ -1,44 +1,51 @@
-import type { Variant } from 'kitbook'
+import type { GroupedPage, Variant, VariantMeta } from 'kitbook'
 import type Component from './+page.svelte'
 
-import { variants as hiVariants } from './mockComponents/Hi.variants'
+// import { variants as hiVariants } from './mockComponents/Hi.variants'
 
-export const variants: Variant<Component>[] = [
-  {
-    name: 'i18n',
-    description: 'Has three languages, which can be toggled between or both can be selected. Variants will will 500 error because they are a sandbox in a sandbox. That is ok as they are just here to show the current language. Try changing the language in the sidebar and use the multi-select feature.',
-    props: {
-      data: {
-        settings: {
-          title: 'i18n Kitbook',
-          description: '',
-          expandTree: true,
-          viewports: [{
-            width: 300,
-            height: 300,
-          }],
-          languages: [
-            { code: 'en', name: 'English' },
-            { code: 'es', name: 'Spanish' },
-            { code: 'fr', name: 'French' },
-          ],
-        },
-        loadedModules: {
-          variantsModule: { variants: hiVariants },
-        },
-        pages: {
-          '/docs/1-get-started': {
-            name: 'get started',
-            url: '/docs/1-get-started',
-            path: '/src/docs/1-get-started.md',
-            extensions: [
-              'md',
-            ],
-          },
-        },
-        pagesStore: null,
-      },
+export const shared_meta: VariantMeta = {}
+
+const shared = {
+} satisfies Partial<Variant<Component>>
+
+const page: GroupedPage = {
+  name: 'get started',
+  url: '/docs/1-get-started',
+  path: '/src/docs/1-get-started.md',
+  extensions: [
+    'md',
+  ],
+}
+
+export const i18n: Variant<Component> = {
+  ...shared,
+  data: {
+    settings: {
+      title: 'i18n Kitbook',
+      description: '',
+      expandTree: true,
+      viewports: [{
+        width: 300,
+        height: 300,
+      }],
+      languages: [
+        { code: 'en', name: 'English' },
+        { code: 'es', name: 'Spanish' },
+        { code: 'fr', name: 'French' },
+      ],
     },
+    loadedModules: {
+      // variantsModule: { variants: hiVariants },
+    },
+    pages: {
+      '/docs/1-get-started': page,
+    },
+    page,
+    pageKey: '/docs/1-get-started',
+    pagesStore: null,
+  },
+  _meta: {
+    description: 'Has three languages, which can be toggled between or both can be selected. Variants will will 500 error because they are a sandbox in a sandbox. That is ok as they are just here to show the current language. Try changing the language in the sidebar and use the multi-select feature.',
     viewports: [{ width: 1000, height: 600 }],
   },
-]
+}

packages/kitbook/src/lib/test/clearSnapshots.ts

@@ -6,7 +6,6 @@ export function clearSnapshots(options: {
   snapshotsDirectory?: string
 } = {}): void {
   const {
-    // eslint-disable-next-line node/prefer-global/process
     projectRoot = process.cwd(),
     snapshotsDirectory = 'e2e/snapshots',
   } = options

packages/kitbook/src/lib/test/getVariants.ts

@@ -2,6 +2,7 @@ import { readdirSync, statSync } from 'node:fs'
 import { join } from 'node:path'
 import { pathToFileURL } from 'node:url'
 import type { VariantsModule } from '../kitbook-types'
+import { convertDeprecatedVariantsToCurrentApi } from '../layout/parseModules/convertDeprecatedToCurrentApi'
 
 /**
  * This function must be run using a root level await call before you define your Playwright tests as if you run Playwright tests from within an async function the runner will error.
@@ -28,7 +29,7 @@ export async function getVariants(options: {
 
   const importPromises = allowedFilepaths.map((path) => {
     const url = pathToFileURL(path).href
-    return import(url).then(module => [url, module]) as Promise<[string, VariantsModule]>
+    return import(url).then(module => [url, convertDeprecatedVariantsToCurrentApi(module)]) as Promise<[string, VariantsModule]>
   })
 
   if (importPromises.length === 0)

packages/kitbook/src/lib/test/runComponentTests.test.ts

@@ -6,7 +6,7 @@ const undefinedLanguage = [{ code: null, name: null }]
 
 const variantModuleWithOneBoringVariant: [string, VariantsModule] = [
   '...src/lib/Foo.variants.ts',
-  { variants: [{ }] },
+  { No_Props: { } },
 ]
 
 describe(prepareVariantsToRun, () => {
@@ -22,8 +22,8 @@ describe(prepareVariantsToRun, () => {
       filepathWithoutExtension: 'lib/Foo',
       viewports: oneViewport,
       languages: twoLanguages,
-      variantName: 'lib/Foo/0',
-      url: '/kitbook/sandbox/lib/Foo?variantIndex=0',
+      variantName: 'lib/Foo/No_Props',
+      url: '/kitbook/sandbox/lib/Foo?variantName=No_Props',
     }
 
     test('standard', () => {
@@ -35,8 +35,7 @@ describe(prepareVariantsToRun, () => {
 
     test('one variant modules language', () => {
       const variantModuleWithOneLanguage: [string, VariantsModule] = ['...src/lib/Foo.variants.ts', {
-        languages: [firstLanguage],
-        variants: [{ }],
+        No_Props: { _meta: { languages: [firstLanguage] } },
       }]
 
       expect(prepareVariantsToRun({
@@ -45,10 +44,10 @@ describe(prepareVariantsToRun, () => {
       })).toEqual([{ ...expected, languages: [firstLanguage] }])
     })
 
-    test('empty language array in variant module', () => {
+    test('empty language array in variant shared_meta', () => {
       const variantModuleWithEmptyLanguageArray: [string, VariantsModule] = ['...src/lib/Foo.variants.ts', {
-        languages: [],
-        variants: [{ }],
+        shared_meta: { languages: [] },
+        No_Props: { },
       }]
 
       expect(prepareVariantsToRun({
@@ -59,7 +58,7 @@ describe(prepareVariantsToRun, () => {
 
     test('empty language array in variant', () => {
       const variantModuleWithEmptyLanguageArray: [string, VariantsModule] = ['...src/lib/Foo.variants.ts', {
-        variants: [{ languages: [] }],
+        No_Props: { _meta: { languages: [] } },
       }]
 
       expect(prepareVariantsToRun({
@@ -77,8 +76,8 @@ describe(prepareVariantsToRun, () => {
       filepathWithoutExtension: 'lib/Foo',
       viewports: oneViewport,
       languages: undefinedLanguage,
-      variantName: 'lib/Foo/0',
-      url: '/sandbox/lib/Foo?variantIndex=0',
+      variantName: 'lib/Foo/No_Props',
+      url: '/sandbox/lib/Foo?variantName=No_Props',
     }])
   })
 
@@ -87,14 +86,14 @@ describe(prepareVariantsToRun, () => {
       kitbookConfig: { viewports: oneViewport, languages: undefinedLanguage, kitbookRoute: '' } as KitbookSettings,
       variantModules: [[
         '...src/lib/Foo.variants.ts',
-        { variants: [{ tests: { skip: true } }] },
+        { No_Props: { _meta: { tests: { skip: true } } } },
       ]],
     })).toEqual([{
       filepathWithoutExtension: 'lib/Foo',
       viewports: oneViewport,
       languages: undefinedLanguage,
-      variantName: 'lib/Foo/0',
-      url: '/sandbox/lib/Foo?variantIndex=0',
+      variantName: 'lib/Foo/No_Props',
+      url: '/sandbox/lib/Foo?variantName=No_Props',
       userAdded: { skip: true },
     }])
   })
@@ -111,16 +110,8 @@ describe(prepareVariantsToRun, () => {
     ]
     const variantModules: [string, VariantsModule][] = [
       ['...src/lib/Foo.variants.ts', {
-        variants: [
-          {
-            name: 'one viewport',
-            viewports: oneViewport,
-          },
-          {
-            name: 'two viewports',
-            viewports: twoViewports,
-          },
-        ],
+        One_Viewport: { _meta: { viewports: oneViewport } },
+        Two_Viewports: { _meta: { viewports: twoViewports } },
       }],
     ] as [string, VariantsModule][]
 
@@ -129,15 +120,15 @@ describe(prepareVariantsToRun, () => {
         {
           filepathWithoutExtension: 'lib/Foo',
           languages: undefinedLanguage,
-          url: '/kitbook/sandbox/lib/Foo?variantIndex=0',
-          variantName: 'lib/Foo/one_viewport',
+          url: '/kitbook/sandbox/lib/Foo?variantName=One_Viewport',
+          variantName: 'lib/Foo/One_Viewport',
           viewports: oneViewport,
         },
         {
           filepathWithoutExtension: 'lib/Foo',
           languages: undefinedLanguage,
-          url: '/kitbook/sandbox/lib/Foo?variantIndex=1',
-          variantName: 'lib/Foo/two_viewports',
+          url: '/kitbook/sandbox/lib/Foo?variantName=Two_Viewports',
+          variantName: 'lib/Foo/Two_Viewports',
           viewports: twoViewports,
         },
       ],

packages/kitbook/src/lib/test/runComponentTests.ts

@@ -1,5 +1,5 @@
 import type { Expect, test as playwrightTest } from '@playwright/test'
-import type { KitbookSettings, Language, Variant, VariantsModule, Viewport } from '../kitbook-types'
+import type { KitbookSettings, Language, VariantMeta, VariantsModule, Viewport } from '../kitbook-types'
 import { mergeUserSettingsWithDefaults } from '../plugins/vite/mergeUserSettingsWithDefaults.js'
 import { preparePath } from './preparePath.js'
 
@@ -20,7 +20,7 @@ export interface VariantToRun {
   url: string
   addLanguageToUrl?: KitbookSettings['addLanguageToUrl']
   filepathWithoutExtension: string
-  userAdded?: Variant<any>['tests']
+  userAdded?: VariantMeta['tests']
 }
 
 export function runComponentTests({
@@ -45,24 +45,24 @@ export function prepareVariantsToRun({ kitbookConfig, variantModules }: KitbookP
 
   const variantsToRun: VariantToRun[] = []
 
-  for (const [path, { variants, viewports: fileViewports, languages: fileLanguages }] of variantModules) {
-    variants.forEach((variant, index) => {
-      const variantViewports = variant.viewports || fileViewports || projectViewports
-      const { directory, filenameWithoutExtension, url } = preparePath({ kitbookRoute, path, index })
+  for (const [path, { shared_meta, ...variants }] of variantModules) {
+    Object.entries(variants).forEach(([name, { _meta }]) => {
+      const variantViewports = _meta?.viewports || shared_meta?.viewports || projectViewports
+      const { directory, filenameWithoutExtension, url } = preparePath({ kitbookRoute, path, variantName: name })
 
       const filepathWithoutExtension = `${directory}/${filenameWithoutExtension}`
-      const variantNameWithSafeCharacters = variant.name?.replace(/[^a-z0-9]/gi, '_')
+      const variantNameWithSafeCharacters = name?.replace(/[^a-z0-9]/gi, '_')
 
-      const variantName = `${filepathWithoutExtension}/${variantNameWithSafeCharacters || index.toString()}`
+      const variantName = `${filepathWithoutExtension}/${variantNameWithSafeCharacters}`
 
       variantsToRun.push({
         variantName,
         viewports: variantViewports,
-        languages: getLanguages({ variantLanguages: variant.languages, moduleLanguages: fileLanguages, activeLanguages: projectLanguages }),
+        languages: getLanguages({ variantLanguages: _meta?.languages, moduleLanguages: shared_meta?.languages, activeLanguages: projectLanguages }),
         url,
         addLanguageToUrl,
         filepathWithoutExtension,
-        userAdded: variant.tests,
+        userAdded: _meta?.tests,
       })
     })
   }