feat: revamp runtime to be based on iframe and vitest

Author: Akryum

.gitignore

@@ -1,7 +1,7 @@
 node_modules/
 dist/
 histoire-dist/
-.histoire/dist/
+.histoire
 .idea
 **/cypress/screenshots/
 **/cypress/videos/

docs/reference/client.md

@@ -47,3 +47,20 @@ import { toggleDark } from 'histoire/client'
 
 toggleDark(true)
 ```
+
+## `onTest`
+
+Registers story-scoped Vitest cases for the current variant.
+
+```ts
+import { onTest } from 'histoire/client'
+import { describe, expect, it } from 'vitest'
+
+onTest(({ canvas }) => {
+  describe('my component', () => {
+    it('renders', () => {
+      expect(canvas.textContent).toContain('Hello')
+    })
+  })
+})
+```

examples/vue3/cypress/e2e/controls.cy.js

@@ -6,40 +6,46 @@ describe('Controls', () => {
     .should('not.be.empty')
     .then(cy.wrap)
 
+  const getControls = () => cy.get('[data-test-id="story-controls"]')
+  const getControl = label => getControls().contains('label', new RegExp(`^${label}$`))
+
   beforeEach(() => {
     cy.visit('/')
     cy.get('[data-test-id="story-list-item"]').contains('Controls').click()
+    cy.get('[data-test-id="story-side-panel"]').should('be.visible')
+    cy.get('[data-test-id="story-side-panel"]').contains('Loading...').should('not.exist')
   })
 
-  it('HstText', () => {
+  it('updates text state', () => {
     getIframeBody().find('.state-output').contains('"text": "Hello"')
-    cy.get('[data-test-id="story-controls"]').contains('HstText').clear().type('Foo')
+    getControl('text').find('input').clear().type('Foo')
     getIframeBody().find('.state-output').contains('"text": "Foo"')
   })
 
-  it('HstCheckbox', () => {
+  it('updates checkbox state', () => {
     getIframeBody().find('.state-output').contains('"checkbox": false')
-    cy.get('[data-test-id="story-controls"]').contains('HstCheckbox').click()
+    getControl('checkbox').click()
     getIframeBody().find('.state-output').contains('"checkbox": true')
-    cy.get('[data-test-id="story-controls"]').contains('HstCheckbox').click()
+    getControl('checkbox').click()
     getIframeBody().find('.state-output').contains('"checkbox": false')
   })
 
-  it('HstNumber', () => {
+  it('updates numeric state', () => {
     getIframeBody().find('.state-output').contains('"number": 20')
-    cy.get('[data-test-id="story-controls"] input[type="number"]').clear().type('42')
-    getIframeBody().find('.state-output').contains('"number": 42')
+    getControl('number').find('input').clear()
+    getControl('number').find('input').type('42')
+    getIframeBody().find('.state-output').contains('"number": "42"')
   })
 
-  it('HstTextarea', () => {
+  it('updates long text state', () => {
     getIframeBody().find('.state-output').contains('"longText": "Longer text..."')
-    cy.get('[data-test-id="story-controls"] textarea').clear().type('Meow meow meow')
+    getControl('longText').find('input').clear().type('Meow meow meow')
     getIframeBody().find('.state-output').contains('"longText": "Meow meow meow"')
   })
 
-  it('HstColorSelect', () => {
+  it('updates color state', () => {
     getIframeBody().find('.state-output').contains('"colorselect": "#000000"')
-    cy.get('[data-test-id="story-controls"]').contains('HstColorSelect').clear().type('#ffffff')
+    getControl('colorselect').find('input').clear().type('#ffffff')
     getIframeBody().find('.state-output').contains('"colorselect": "#ffffff"')
   })
 })

examples/vue3/cypress/e2e/story-tests-panel.cy.js

@@ -0,0 +1,122 @@
+/// <reference types="cypress" />
+
+describe('Preview tests panel', () => {
+  const storyPath = 'src/components/VitestMocking.story.vue'
+  const hmrInsertionMarker = '    // HMR_TEST_INSERTION_POINT'
+  let originalStorySource = ''
+
+  const getIframeBody = () => cy.get('iframe[data-test-id="preview-iframe"]')
+    .its('0.contentDocument.body')
+    .should('not.be.empty')
+    .then(cy.wrap)
+
+  const assertMockedGreeting = () => {
+    getIframeBody().find('iframe').should('have.length', 0)
+    getIframeBody().contains('Mocked by Vitest for Vitest browser mode', {
+      timeout: 20000,
+    })
+    getIframeBody().should('not.contain', 'Failed to resolve vitest:mocks:resolveMock in time')
+  }
+
+  function openVitestStory() {
+    cy.get('[data-test-id="story-list-item"]').contains('Vitest Mocking').click()
+    cy.location('search').should('include', 'variantId=src-components-vitestmocking-story-vue-0')
+  }
+
+  function openTestsPanel() {
+    cy.get('[data-test-id="story-tests-tab"]:visible').click()
+    cy.get('[data-test-id="story-side-panel"]').should('be.visible')
+    cy.get('[data-test-id="story-side-panel"]').contains('Loading...').should('not.exist')
+  }
+
+  function assertCollectedDefinitions(count) {
+    cy.get('iframe[data-test-id="preview-iframe"]')
+      .its('0.contentWindow.__HST_TEST_DEFINITIONS__')
+      .should((definitions) => {
+        expect(Array.isArray(definitions)).to.equal(true)
+        expect(definitions).to.have.length(count)
+      })
+  }
+
+  function assertTestsTabCount(count) {
+    cy.get('[data-test-id="story-tests-tab-count"]:visible')
+      .should('have.text', `${count}`)
+  }
+
+  beforeEach(() => {
+    cy.readFile(storyPath).then((source) => {
+      originalStorySource = source
+    })
+  })
+
+  afterEach(() => {
+    if (!originalStorySource) {
+      return
+    }
+
+    cy.writeFile(storyPath, originalStorySource)
+  })
+
+  it('collects story tests registered from a single onTest callback', () => {
+    cy.viewport(1600, 1000)
+    cy.visit('/')
+
+    openVitestStory()
+    assertCollectedDefinitions(3)
+    assertTestsTabCount(3)
+    assertMockedGreeting()
+
+    openTestsPanel()
+    cy.contains('button', 'Run tests').should('be.visible')
+    cy.get('[data-test-id="story-test-row"]').should('have.length', 3)
+    cy.get('[data-test-id="story-test-row"]').each(($row) => {
+      cy.wrap($row).contains('Not run')
+    })
+
+    cy.contains('button', 'Run tests').click()
+    cy.get('[data-test-id="story-test-row"]').should('have.length', 3)
+    cy.contains('[data-test-id="story-test-row"]', 'renders the mocked dependency output').contains('passed')
+    cy.contains('[data-test-id="story-test-row"]', 'tracks calls through the mocked module function').contains('passed')
+    cy.contains('[data-test-id="story-test-row"]', 'fails').as('failedRow')
+    cy.get('@failedRow').contains('failed')
+    cy.get('@failedRow').contains('This test is expected to fail')
+  })
+
+  it('refreshes mocked story tests after hot updates', () => {
+    cy.viewport(1600, 1000)
+    cy.visit('/')
+
+    openVitestStory()
+    openTestsPanel()
+    assertCollectedDefinitions(3)
+    assertTestsTabCount(3)
+    cy.get('[data-test-id="story-test-row"]').should('have.length', 3)
+    assertMockedGreeting()
+
+    cy.then(() => {
+      const updatedStorySource = originalStorySource.replace(hmrInsertionMarker, `    it('updates the tests panel after hot reload', () => {
+      expect(canvas.textContent).toContain('Mocked by Vitest for Vitest browser mode')
+    })
+${hmrInsertionMarker}`)
+
+      expect(updatedStorySource).not.to.equal(originalStorySource)
+      cy.writeFile(storyPath, updatedStorySource)
+    })
+
+    assertCollectedDefinitions(4)
+    assertTestsTabCount(4)
+    cy.get('[data-test-id="story-test-row"]', {
+      timeout: 20000,
+    }).should('have.length', 4)
+    assertMockedGreeting()
+
+    cy.writeFile(storyPath, originalStorySource)
+
+    assertCollectedDefinitions(3)
+    assertTestsTabCount(3)
+    cy.get('[data-test-id="story-test-row"]', {
+      timeout: 20000,
+    }).should('have.length', 3)
+    assertMockedGreeting()
+  })
+})

examples/vue3/cypress/e2e/vitest-story.cy.js

@@ -0,0 +1,51 @@
+/// <reference types="cypress" />
+
+describe('Vitest story runtime', () => {
+  const getIframeBody = () => cy.get('iframe[data-test-id="preview-iframe"]')
+    .its('0.contentDocument.body')
+    .should('not.be.empty')
+    .then(cy.wrap)
+
+  const assertMockedGreeting = () => {
+    getIframeBody().find('iframe').should('have.length', 0)
+    getIframeBody().contains('Mocked by Vitest for Vitest browser mode', {
+      timeout: 10000,
+    })
+  }
+
+  function openVitestStory() {
+    cy.get('[data-test-id="story-list-item"]').contains('Vitest Mocking').click()
+    cy.location('search').should('include', 'variantId=src-components-vitestmocking-story-vue-0')
+
+    cy.get('body').then(($body) => {
+      if ($body.find('[data-test-id="story-variant-list-item"]').length) {
+        cy.contains('[data-test-id="story-variant-list-item"]', 'mocked module in story setup').click()
+      }
+    })
+  }
+
+  it('reopens the story without losing the manual Vitest mock state', () => {
+    cy.viewport(1600, 1000)
+    cy.visit('/')
+    openVitestStory()
+
+    assertMockedGreeting()
+
+    cy.get('[data-test-id="story-list-item"]').contains('BaseButton').click()
+    cy.location('pathname').should('include', '/story/src-components-basebutton-story-vue')
+
+    openVitestStory()
+    assertMockedGreeting()
+  })
+
+  it('shows the tests pane without getting stuck in loading', () => {
+    cy.viewport(1600, 1000)
+    cy.visit('/')
+    openVitestStory()
+
+    cy.contains('button, a', 'Tests').click()
+    cy.get('[data-test-id="story-side-panel"]').should('be.visible')
+    cy.get('[data-test-id="story-side-panel"]').contains('Loading...').should('not.exist')
+    cy.contains('button', 'Run tests').should('be.visible')
+  })
+})

examples/vue3/package.json

@@ -32,6 +32,7 @@
     "nodemon": "^3.1.7",
     "sass": "^1.82.0",
     "start-server-and-test": "^2.0.8",
-    "vite": "catalog:"
+    "vite": "catalog:",
+    "vitest": "4.0.16"
   }
 }

examples/vue3/src/components/VitestMockedGreeting.vue

@@ -0,0 +1,23 @@
+<script setup lang="ts">
+import { computed } from 'vue'
+import { getGreeting } from './vitest-mocking-greeting'
+
+const props = withDefaults(defineProps<{
+  name?: string
+}>(), {
+  name: 'Vitest browser mode',
+})
+
+const greeting = computed(() => getGreeting(props.name))
+</script>
+
+<template>
+  <div class="htw-inline-flex htw-flex-col htw-gap-2 htw-p-4">
+    <div class="htw-text-xs htw-font-semibold htw-uppercase htw-tracking-[0.18em]">
+      Vitest Mock
+    </div>
+    <div class="htw-text-lg htw-font-medium">
+      {{ greeting }}
+    </div>
+  </div>
+</template>

examples/vue3/src/components/VitestMocking.story.vue

@@ -0,0 +1,37 @@
+<script setup lang="ts">
+import { onTest } from 'histoire/client'
+import { describe, expect, it, vi } from 'vitest'
+import { getGreeting } from './vitest-mocking-greeting'
+import VitestMockedGreeting from './VitestMockedGreeting.vue'
+
+vi.mock('./vitest-mocking-greeting', () => ({
+  getGreeting: vi.fn((name: string) => `Mocked by Vitest for ${name}`),
+}))
+
+const mockedGetGreeting = vi.mocked(getGreeting)
+
+onTest(({ canvas }) => {
+  describe('mocked module in story setup', () => {
+    it('renders the mocked dependency output', () => {
+      expect(canvas.textContent).toContain('Mocked by Vitest for Vitest browser mode')
+    })
+
+    it('tracks calls through the mocked module function', () => {
+      expect(vi.isMockFunction(getGreeting)).toBe(true)
+      expect(mockedGetGreeting).toHaveBeenCalledWith('Vitest browser mode')
+    })
+    // HMR_TEST_INSERTION_POINT
+    it('fails', () => {
+      expect(canvas.textContent).toContain('This test is expected to fail')
+    })
+  })
+})
+</script>
+
+<template>
+  <Story title="Vitest Mocking">
+    <Variant title="mocked module in story setup">
+      <VitestMockedGreeting />
+    </Variant>
+  </Story>
+</template>

examples/vue3/src/components/vitest-mocking-greeting.ts

@@ -0,0 +1,3 @@
+export function getGreeting(name: string) {
+  return `Original greeting for ${name}`
+}

packages/histoire-app/src/app/App.vue

@@ -96,7 +96,7 @@ const commandStore = useCommandStore()
 
 <template>
   <div
-    v-if="storyStore.currentStory"
+    v-if="storyStore.currentStory && !storyStore.currentStory.file?.hasVitestMocks"
     class="histoire-app htw-hidden"
   >
     <GenericMountStory