feat: stubs mounting option

src/mount.ts

@@ -5,6 +5,7 @@ import {
   defineComponent,
   VNodeNormalizedChildren,
   ComponentOptions,
+  transformVNodeArgs,
   Plugin,
   Directive,
   Component,
@@ -15,6 +16,7 @@ import { createWrapper } from './vue-wrapper'
 import { createEmitMixin } from './emitMixin'
 import { createDataMixin } from './dataMixin'
 import { MOUNT_ELEMENT_ID } from './constants'
+import { stubComponents } from './stubs'
 
 type Slot = VNode | string | { render: Function }
 
@@ -29,6 +31,7 @@ interface MountingOptions {
     plugins?: Plugin[]
     mixins?: ComponentOptions[]
     mocks?: Record<string, any>
+    stubs?: Record<any, any>
     provide?: Record<any, any>
     // TODO how to type `defineComponent`? Using `any` for now.
     components?: Record<string, Component | object>
@@ -72,6 +75,7 @@ export function mount(originalComponent: any, options?: MountingOptions) {
 
   // create the wrapper component
   const Parent = defineComponent({
+    name: 'VTU_COMPONENT',
     render() {
       return h(component, props, slots)
     }
@@ -133,6 +137,13 @@ export function mount(originalComponent: any, options?: MountingOptions) {
   const { emitMixin, events } = createEmitMixin()
   vm.mixin(emitMixin)
 
+  // stubs
+  if (options?.global?.stubs) {
+    stubComponents(options.global.stubs)
+  } else {
+    transformVNodeArgs()
+  }
+
   // mount the app!
   const app = vm.mount(el)
 

src/stubs.ts

@@ -0,0 +1,67 @@
+import { transformVNodeArgs, h } from 'vue'
+import kebabCase from 'lodash/kebabCase'
+
+import { pascalCase } from './utils'
+
+interface IStubOptions {
+  name?: string
+}
+
+// TODO: figure out how to type this
+type VNodeArgs = any[]
+
+export const createStub = (options: IStubOptions) => {
+  const tag = options.name ? `${options.name}-stub` : 'anonymous-stub'
+  const render = () => h(tag)
+
+  return { name: tag, render }
+}
+
+const resolveComponentStubByName = (name: string, stubs: Record<any, any>) => {
+  const pascal = pascalCase(name)
+  const kebab = kebabCase(name)
+
+  for (const [key, value] of Object.entries(stubs)) {
+    if (name === pascal || name === kebab) {
+      return value
+    }
+  }
+}
+
+const isHTMLElement = (args: VNodeArgs) =>
+  Array.isArray(args) && typeof args[0] === 'string'
+const isCommentOrFragment = (args: VNodeArgs) => typeof args[0] === 'symbol'
+const isParent = (args: VNodeArgs) =>
+  typeof args[0] === 'object' && args[0]['name'] === 'VTU_COMPONENT'
+const isComponent = (args: VNodeArgs) => typeof args[0] === 'object'
+
+export function stubComponents(stubs: Record<any, any>) {
+  transformVNodeArgs((args) => {
+    if (isHTMLElement(args) || isCommentOrFragment(args) || isParent(args)) {
+      return args
+    }
+
+    if (isComponent(args)) {
+      const name = args[0]['name']
+      if (!name) {
+        return args
+      }
+
+      const stub = resolveComponentStubByName(name, stubs)
+      // we return a stub by matching Vue's `h` function
+      // where the signature is h(Component, props)
+
+      // default stub
+      if (stub === true) {
+        return [createStub({ name }), {}]
+      }
+
+      // custom implementation
+      if (typeof stub === 'object') {
+        return [stubs[name], {}]
+      }
+    }
+
+    return args
+  })
+}

src/utils.ts

@@ -0,0 +1,5 @@
+import camelCase from 'lodash/camelCase'
+import upperFirst from 'lodash/upperFirst'
+import flow from 'lodash/flow'
+
+export const pascalCase = flow(camelCase, upperFirst)

tests/mountingOptions/stubs.global.spec.ts

@@ -0,0 +1,201 @@
+import { h, ComponentOptions } from 'vue'
+
+import { mount } from '../../src'
+import Hello from '../components/Hello.vue'
+
+describe('mounting options: stubs', () => {
+  it('stubs in a fragment', () => {
+    const Foo = {
+      name: 'Foo',
+      render() {
+        return h('p')
+      }
+    }
+    const Component: ComponentOptions = {
+      render() {
+        return h(() => [h('div'), h(Foo)])
+      }
+    }
+
+    const wrapper = mount(Component, {
+      global: {
+        stubs: {
+          Foo: true
+        }
+      }
+    })
+
+    expect(wrapper.html()).toBe('<div></div><foo-stub></foo-stub>')
+  })
+
+  it('prevents lifecycle hooks triggering in a stub', () => {
+    const onBeforeMount = jest.fn()
+    const beforeCreate = jest.fn()
+    const Foo = {
+      name: 'Foo',
+      setup() {
+        onBeforeMount(onBeforeMount)
+        return () => h('div')
+      },
+      beforeCreate
+    }
+    const Comp = {
+      render() {
+        return h(Foo)
+      }
+    }
+
+    const wrapper = mount(Comp, {
+      global: {
+        stubs: {
+          Foo: true
+        }
+      }
+    })
+
+    expect(wrapper.html()).toBe('<foo-stub></foo-stub>')
+    expect(onBeforeMount).not.toHaveBeenCalled()
+    expect(beforeCreate).not.toHaveBeenCalled()
+  })
+
+  it('uses a custom stub implementation', () => {
+    const onBeforeMount = jest.fn()
+    const FooStub = {
+      name: 'FooStub',
+      setup() {
+        onBeforeMount(onBeforeMount)
+        return () => h('div', 'foo stub')
+      }
+    }
+    const Foo = {
+      name: 'Foo',
+      render() {
+        return h('div', 'real foo')
+      }
+    }
+
+    const Comp = {
+      render() {
+        return h(Foo)
+      }
+    }
+
+    const wrapper = mount(Comp, {
+      global: {
+        stubs: {
+          Foo: FooStub
+        }
+      }
+    })
+
+    expect(onBeforeMount).toHaveBeenCalled()
+    expect(wrapper.html()).toBe('<div>foo stub</div>')
+  })
+
+  it('uses an sfc as a custom stub', () => {
+    const created = jest.fn()
+    const HelloComp = {
+      name: 'Hello',
+      created() {
+        created()
+      },
+      render() {
+        return h('span', 'real implementation')
+      }
+    }
+
+    const Comp = {
+      render() {
+        return h(HelloComp)
+      }
+    }
+
+    const wrapper = mount(Comp, {
+      global: {
+        stubs: {
+          Hello: Hello
+        }
+      }
+    })
+
+    expect(created).not.toHaveBeenCalled()
+    expect(wrapper.html()).toBe(
+      '<div id="root"><div id="msg">Hello world</div></div>'
+    )
+  })
+
+  it('stubs using inline components', () => {
+    const Foo = {
+      name: 'Foo',
+      render() {
+        return h('p')
+      }
+    }
+    const Bar = {
+      name: 'Bar',
+      render() {
+        return h('p')
+      }
+    }
+    const Component: ComponentOptions = {
+      render() {
+        return h(() => [h(Foo), h(Bar)])
+      }
+    }
+
+    const wrapper = mount(Component, {
+      global: {
+        stubs: {
+          Foo: {
+            template: '<span />'
+          },
+          Bar: {
+            render() {
+              return h('div')
+            }
+          }
+        }
+      }
+    })
+
+    expect(wrapper.html()).toBe('<span></span><div></div>')
+  })
+
+  it('stubs a component with a kabeb-case name', () => {
+    const FooBar = {
+      name: 'foo-bar',
+      render: () => h('span', 'real foobar')
+    }
+    const Comp = {
+      render: () => h(FooBar)
+    }
+    const wrapper = mount(Comp, {
+      global: {
+        stubs: {
+          FooBar: true
+        }
+      }
+    })
+
+    expect(wrapper.html()).toBe('<foo-bar-stub></foo-bar-stub>')
+  })
+
+  it('stubs a component with a PascalCase name', () => {
+    const FooBar = {
+      name: 'FooBar',
+      render: () => h('span', 'real foobar')
+    }
+    const Comp = {
+      render: () => h(FooBar)
+    }
+    const wrapper = mount(Comp, {
+      global: {
+        stubs: {
+          'foo-bar': true
+        }
+      }
+    })
+
+    expect(wrapper.html()).toBe('<foobar-stub></foobar-stub>')
+  })
+})