feat: add support of arbitrary mounting point via attachTo option

This allows for users to specify where in the document their component should attach, either through
a CSS selector string or a provided HTMLElement. This option is passed through directly to the
vm.$mount method that is called as part of mount.js. This enables testing of SSR code with Vue test
utils as well as rendering of applications via Vue test utiles in contexts that aren't 100% Vue

fixes vuejs#1492

Author: jnields

Diff for: flow/options.flow.js

@@ -1,6 +1,7 @@
 declare type Options = {
   // eslint-disable-line no-undef
   attachToDocument?: boolean,
+  attachTo?: HTMLElement | string,
   propsData?: Object,
   mocks?: Object,
   methods?: { [key: string]: Function },
@@ -17,6 +18,7 @@ declare type Options = {
 }
 
 declare type NormalizedOptions = {
+  attachTo?: HTMLElement | string,
   attachToDocument?: boolean,
   propsData?: Object,
   mocks: Object,

Diff for: packages/shared/validate-options.js

@@ -1,11 +1,13 @@
 import {
   isPlainObject,
   isFunctionalComponent,
-  isConstructor
+  isConstructor,
+  isDomSelector,
+  isHTMLElement
 } from './validators'
 import { VUE_VERSION } from './consts'
 import { compileTemplateForSlots } from './compile-template'
-import { throwError } from './util'
+import { throwError, warn } from './util'
 import { validateSlots } from './validate-slots'
 
 function vueExtendUnsupportedOption(option) {
@@ -22,6 +24,20 @@ function vueExtendUnsupportedOption(option) {
 const UNSUPPORTED_VERSION_OPTIONS = ['mocks', 'stubs', 'localVue']
 
 export function validateOptions(options, component) {
+  if (
+    options.attachTo &&
+    !isHTMLElement(options.attachTo) &&
+    !isDomSelector(options.attachTo)
+  ) {
+    throwError(
+      `options.attachTo should be a valid HTMLElement or CSS selector string`
+    )
+  }
+  if ('attachToDocument' in options) {
+    warn(
+      `options.attachToDocument is deprecated in favor of options.attachTo and will be removed in a future release`
+    )
+  }
   if (options.parentComponent && !isPlainObject(options.parentComponent)) {
     throwError(
       `options.parentComponent should be a valid Vue component options object`

Diff for: packages/shared/validators.js

@@ -112,6 +112,14 @@ export function isPlainObject(c: any): boolean {
   return Object.prototype.toString.call(c) === '[object Object]'
 }
 
+export function isHTMLElement(c: any): boolean {
+  if (typeof HTMLElement === 'undefined') {
+    return false
+  }
+  // eslint-disable-next-line no-undef
+  return c instanceof HTMLElement
+}
+
 export function isRequiredComponent(name: string): boolean {
   return (
     name === 'KeepAlive' || name === 'Transition' || name === 'TransitionGroup'

Diff for: packages/test-utils/src/mount.js

@@ -28,15 +28,16 @@ export default function mount(component, options = {}) {
 
   const parentVm = createInstance(component, mergedOptions, _Vue)
 
-  const el = options.attachToDocument ? createElement() : undefined
+  const el =
+    options.attachTo || (options.attachToDocument ? createElement() : undefined)
   const vm = parentVm.$mount(el)
 
   component._Ctor = {}
 
   throwIfInstancesThrew(vm)
 
   const wrapperOptions = {
-    attachedToDocument: !!mergedOptions.attachToDocument
+    attachedToDocument: !!el
   }
 
   const root = parentVm.$options._isFunctionalContainer

Diff for: test/specs/mount.spec.js

@@ -293,6 +293,7 @@ describeRunIf(process.env.TEST_ENV !== 'node', 'mount', () => {
     expect(wrapper.vm.$options.context).to.equal(undefined)
     expect(wrapper.vm.$options.attrs).to.equal(undefined)
     expect(wrapper.vm.$options.listeners).to.equal(undefined)
+    wrapper.destroy()
   })
 
   itDoNotRunIf(vueVersion < 2.3, 'injects store correctly', () => {
@@ -366,6 +367,7 @@ describeRunIf(process.env.TEST_ENV !== 'node', 'mount', () => {
         '  <p class="prop-2"></p>\n' +
         '</div>'
     )
+    wrapper.destroy()
   })
 
   it('overwrites the component options with the instance options', () => {

Diff for: test/specs/mounting-options/attachTo.spec.js

@@ -0,0 +1,62 @@
+import { describeWithShallowAndMount } from '~resources/utils'
+
+const innerHTML = '<input><span>Hello world</span>'
+const outerHTML = `<div id="attach-to">${innerHTML}</div>`
+const ssrHTML = `<div id="attach-to" data-server-rendered="true">${innerHTML}</div>`
+const template = '<div id="attach-to"><input /><span>Hello world</span></div>'
+const TestComponent = { template }
+
+describeWithShallowAndMount('options.attachTo', mountingMethod => {
+  it('attaches to a provided HTMLElement', () => {
+    const div = document.createElement('div')
+    div.id = 'root'
+    document.body.appendChild(div)
+    expect(document.getElementById('root')).to.not.be.null
+    expect(document.getElementById('attach-to')).to.be.null
+    const wrapper = mountingMethod(TestComponent, {
+      attachTo: div
+    })
+    expect(document.getElementById('root')).to.be.null
+    expect(document.getElementById('attach-to')).to.not.be.null
+    expect(document.getElementById('attach-to').outerHTML).to.equal(outerHTML)
+    expect(wrapper.options.attachedToDocument).to.equal(true)
+    wrapper.destroy()
+    expect(document.getElementById('attach-to')).to.be.null
+  })
+  it('attaches to a provided CSS selector string', () => {
+    const div = document.createElement('div')
+    div.id = 'root'
+    document.body.appendChild(div)
+    expect(document.getElementById('root')).to.not.be.null
+    expect(document.getElementById('attach-to')).to.be.null
+    const wrapper = mountingMethod(TestComponent, {
+      attachTo: '#root'
+    })
+    expect(document.getElementById('root')).to.be.null
+    expect(document.getElementById('attach-to')).to.not.be.null
+    expect(document.getElementById('attach-to').outerHTML).to.equal(outerHTML)
+    expect(wrapper.options.attachedToDocument).to.equal(true)
+    wrapper.destroy()
+    expect(document.getElementById('attach-to')).to.be.null
+  })
+
+  it('correctly hydrates markup', () => {
+    expect(document.getElementById('attach-to')).to.be.null
+
+    const div = document.createElement('div')
+    div.id = 'attach-to'
+    div.setAttribute('data-server-rendered', 'true')
+    div.innerHTML = innerHTML
+    document.body.appendChild(div)
+    expect(div.outerHTML).to.equal(ssrHTML)
+    const wrapper = mountingMethod(TestComponent, {
+      attachTo: '#attach-to'
+    })
+    const rendered = document.getElementById('attach-to')
+    expect(rendered).to.not.be.null
+    expect(rendered.outerHTML).to.equal(outerHTML)
+    expect(wrapper.options.attachedToDocument).to.equal(true)
+    wrapper.destroy()
+    expect(document.getElementById('attach-to')).to.be.null
+  })
+})