feat(renderToString) Add renderToString method (#435)

Author: eddyerburgh

docs/en/README.md

@@ -18,6 +18,7 @@
 * [API](api/README.md)
   * [mount](api/mount.md)
   * [shallow](api/shallow.md)
+  * [renderToString](api/renderToString.md)
   * [Mounting Options](api/options.md)
     - [context](api/options.md#context)
     - [slots](api/options.md#slots)

docs/en/SUMMARY.md

@@ -14,6 +14,7 @@
 * [API](api/README.md)
   * [mount](api/mount.md)
   * [shallow](api/shallow.md)
+  * [renderToString](api/renderToString.md)
   * [Mounting Options](api/options.md)
     - [context](api/options.md#context)
     - [slots](api/options.md#slots)

docs/en/api/README.md

@@ -2,6 +2,7 @@
 
 * [mount](./mount.md)
 * [shallow](./shallow.md)
+* [renderToString](./renderToString.md)
 * [Mounting Options](./options.md)
   - [context](./options.md#context)
   - [slots](./options.md#slots)

docs/en/api/renderToString.md

@@ -0,0 +1,103 @@
+# `renderToString(component {, options}])`
+
+- **Arguments:**
+
+  - `{Component} component`
+  - `{Object} options`
+    - `{Object} context`
+      - `{Array<Component|Object>|Component} children`
+    - `{Object} slots`
+        - `{Array<Componet|Object>|Component|String} default`
+        - `{Array<Componet|Object>|Component|String} named`
+    - `{Object} mocks`
+    - `{Object|Array<string>} stubs`
+    - `{Vue} localVue`
+
+- **Returns:** `{string}`
+
+- **Options:**
+
+See [options](./options.md)
+
+- **Usage:**
+
+Renders a component to HTML.
+
+`renderToString` uses [`vue-server-renderer`](https://ssr.vuejs.org/en/basic.html) under the hood, to render a component to HTML.
+
+**Without options:**
+
+```js
+import { renderToString } from '@vue/test-utils'
+import { expect } from 'chai'
+import Foo from './Foo.vue'
+
+describe('Foo', () => {
+  it('renders a div', () => {
+    const renderedString = renderToString(Foo)
+    expect(renderedString).toContain('<div></div>')
+  })
+})
+```
+
+**With Vue options:**
+
+```js
+import { renderToString } from '@vue/test-utils'
+import { expect } from 'chai'
+import Foo from './Foo.vue'
+
+describe('Foo', () => {
+  it('renders a div', () => {
+    const renderedString = renderToString(Foo, {
+      propsData: {
+        color: 'red'
+      }
+    })
+    expect(renderedString).toContain('red')
+  })
+})
+```
+
+**Default and named slots:**
+
+```js
+import { renderToString } from '@vue/test-utils'
+import { expect } from 'chai'
+import Foo from './Foo.vue'
+import Bar from './Bar.vue'
+import FooBar from './FooBar.vue'
+
+describe('Foo', () => {
+  it('renders a div', () => {
+    const renderedString = renderToString(Foo, {
+      slots: {
+        default: [Bar, FooBar],
+        fooBar: FooBar, // Will match <slot name="FooBar" />,
+        foo: '<div />'
+      }
+    })
+    expect(renderedString).toContain('<div></div>')
+  })
+})
+```
+
+**Stubbing global properties:**
+
+```js
+import { renderToString } from '@vue/test-utils'
+import { expect } from 'chai'
+import Foo from './Foo.vue'
+
+describe('Foo', () => {
+  it('renders a div', () => {
+    const $route = { path: 'http://www.example-path.com' }
+    const renderedString = renderToString(Foo, {
+      mocks: {
+        $route
+      }
+    })
+    expect(renderedString).toContain($route.path)
+  })
+})
+```

flow/modules.flow.js

@@ -15,3 +15,7 @@ declare module 'lodash/cloneDeep' {
 declare module 'vue-template-compiler' {
   declare module.exports: any;
 }
+
+declare module 'vue-server-renderer' {
+  declare module.exports: any;
+}

package.json

@@ -88,6 +88,7 @@
     "vue-class-component": "^6.1.2",
     "vue-loader": "^13.6.2",
     "vue-router": "^3.0.1",
+    "vue-server-renderer": "2.5.13",
     "vue-template-compiler": "^2.5.13",
     "vuetify": "^0.16.9",
     "vuex": "^3.0.1",
@@ -96,6 +97,7 @@
   },
   "peerDependencies": {
     "vue": "2.x",
+    "vue-server-renderer": "2.x",
     "vue-template-compiler": "^2.x"
   },
   "dependencies": {

scripts/test-compat.sh

@@ -4,7 +4,7 @@ set -e
 
 test_version_number(){
   echo "running unit tests with Vue $1"
-  yarn add vue@$1 vue-template-compiler@$1
+  yarn add vue@$1 vue-template-compiler@$1 vue-server-renderer@$1
   yarn test:unit
   yarn test:unit:karma
 }

src/index.js

@@ -1,5 +1,6 @@
 import shallow from './shallow'
 import mount from './mount'
+import renderToString from './renderToString'
 import createLocalVue from './create-local-vue'
 import TransitionStub from './components/TransitionStub'
 import TransitionGroupStub from './components/TransitionGroupStub'
@@ -11,6 +12,7 @@ export default {
   config,
   mount,
   shallow,
+  renderToString,
   TransitionStub,
   TransitionGroupStub,
   RouterLinkStub

src/lib/add-slots.js

@@ -54,6 +54,9 @@ function addSlots (vm: Component, slots: Object): void {
 
     if (Array.isArray(slots[key])) {
       slots[key].forEach((slotValue) => {
+        if (!isValidSlot(slotValue)) {
+          throwError('slots[key] must be a Component, string or an array of Components')
+        }
         addSlotToVm(vm, key, slotValue)
       })
     } else {

src/mount.js

@@ -11,8 +11,8 @@ import errorHandler from './lib/error-handler'
 import { findAllVueComponentsFromVm } from './lib/find-vue-components'
 
 Vue.config.productionTip = false
-Vue.config.errorHandler = errorHandler
 Vue.config.devtools = false
+Vue.config.errorHandler = errorHandler
 
 export default function mount (component: Component, options: Options = {}): VueWrapper {
   // Remove cached constructor

src/renderToString.js

@@ -0,0 +1,39 @@
+// @flow
+
+import Vue from 'vue'
+import createInstance from './lib/create-instance'
+import './lib/polyfills/object-assign-polyfill'
+import { throwError } from './lib/util'
+
+Vue.config.productionTip = false
+Vue.config.devtools = false
+
+export default function renderToString (component: Component, options: Options = {}): string {
+  let renderer
+  try {
+    renderer = require('vue-server-renderer').createRenderer()
+  } catch (e) {}
+
+  if (!renderer) {
+    throwError('renderToString must be run in node. It cannot be run in a browser')
+  }
+  // Remove cached constructor
+  delete component._Ctor
+
+  if (options.attachToDocument) {
+    throwError('you cannot use attachToDocument with renderToString')
+  }
+
+  const vm = createInstance(component, options)
+
+  let renderedString = ''
+
+  // $FlowIgnore
+  renderer.renderToString(vm, (err, res) => {
+    if (err) {
+      console.log(err)
+    }
+    renderedString = res
+  })
+  return renderedString
+}

test/resources/test-utils.js

@@ -1,10 +1,12 @@
 /* global describe, it*/
 
 import Vue from 'vue'
-import { shallow, mount } from '~vue-test-utils'
+import { shallow, mount, renderToString } from '~vue-test-utils'
 
 export const vueVersion = Number(`${Vue.version.split('.')[0]}.${Vue.version.split('.')[1]}`)
 
+export const isRunningJSDOM = navigator.userAgent.includes && navigator.userAgent.includes('jsdom')
+
 export function injectSupported () {
   return vueVersion > 2.2
 }
@@ -21,20 +23,43 @@ export function functionalSFCsSupported () {
   return vueVersion >= 2.5
 }
 
+const shallowAndMount = [mount, shallow]
+const shallowMountAndRender = isRunningJSDOM
+  ? [mount, shallow, renderToString]
+  : [mount, shallow]
+
 export function describeWithShallowAndMount (spec, cb) {
-  ;[mount, shallow].forEach(method => {
+  shallowAndMount.forEach(method => {
     describe(`${spec} with ${method.name}`, () => cb(method))
   })
 }
 
 describeWithShallowAndMount.skip = function (spec, cb) {
-  ;[mount, shallow].forEach(method => {
+  shallowAndMount.forEach(method => {
     describe.skip(`${spec} with ${method.name}`, () => cb(method))
   })
 }
 
 describeWithShallowAndMount.only = function (spec, cb) {
-  ;[mount, shallow].forEach(method => {
+  shallowAndMount.forEach(method => {
+    describe.only(`${spec} with ${method.name}`, () => cb(method))
+  })
+}
+
+export function describeWithMountingMethods (spec, cb) {
+  shallowMountAndRender.forEach(method => {
+    describe(`${spec} with ${method.name}`, () => cb(method))
+  })
+}
+
+describeWithMountingMethods.skip = function (spec, cb) {
+  shallowMountAndRender.forEach(method => {
+    describe.skip(`${spec} with ${method.name}`, () => cb(method))
+  })
+}
+
+describeWithMountingMethods.only = function (spec, cb) {
+  shallowMountAndRender.forEach(method => {
     describe.only(`${spec} with ${method.name}`, () => cb(method))
   })
 }

test/setup/karma.conf.js

@@ -7,10 +7,10 @@ module.exports = function (config) {
     reporters: ['spec'],
     files: [
       '../../node_modules/babel-polyfill/dist/polyfill.js',
-      '../specs/**/*.+(vue|js)'
+      'load-tests.js'
     ],
     preprocessors: {
-      '../specs/**/*.+(vue|js)': ['webpack', 'sourcemap']
+      'load-tests.js': ['webpack', 'sourcemap']
     },
     client: { mocha: { timeout: 20000 }},
     webpack: webpackConfig,

test/setup/load-tests.js

@@ -0,0 +1,3 @@
+const testsContext = require.context('../specs', true, /\.spec\.(js|vue)$/)
+
+testsContext.keys().forEach(testsContext)

test/setup/webpack.test.config.js

@@ -38,5 +38,8 @@ module.exports = {
     devtoolModuleFilenameTemplate: '[absolute-resource-path]',
     devtoolFallbackModuleFilenameTemplate: '[absolute-resource-path]?[hash]'
   },
-  devtool: '#inline-cheap-module-source-map'
+  devtool: '#inline-cheap-module-source-map',
+  node: {
+    fs: 'empty'
+  }
 }

test/specs/components/TransitionGroupStub.spec.js

@@ -22,7 +22,6 @@ describe('TransitionGroupStub', () => {
       }),
       watch: {
         someWatchedData (newData) {
-          console.log('asd')
           this.someData = newData
         }
       },

test/specs/mounting-options/attachToDocument.spec.js

@@ -1,5 +1,9 @@
 import { compileToFunctions } from 'vue-template-compiler'
-import { describeWithShallowAndMount } from '~resources/test-utils'
+import {
+  describeWithShallowAndMount,
+  isRunningJSDOM
+} from '~resources/test-utils'
+import { renderToString } from '~vue-test-utils'
 
 describeWithShallowAndMount('options.attachToDocument', (mountingMethod) => {
   it('returns VueWrapper with attachedToDocument set to true when passed attachToDocument in options', () => {
@@ -8,3 +12,16 @@ describeWithShallowAndMount('options.attachToDocument', (mountingMethod) => {
     expect(wrapper.options.attachedToDocument).to.equal(true)
   })
 })
+
+describe('options.attachToDocument with renderToString', () => {
+  it('throws error that renderToString does not accept attachToDocument', () => {
+    // renderToString can only be run in node
+    if (!isRunningJSDOM) {
+      return
+    }
+    const compiled = compileToFunctions('<div><input /></div>')
+    const fn = () => renderToString(compiled, { attachToDocument: true })
+    const message = '[vue-test-utils]: you cannot use attachToDocument with renderToString'
+    expect(fn).to.throw().with.property('message', message)
+  })
+})

test/specs/mounting-options/attrs.spec.js

@@ -1,9 +1,13 @@
 import { compileToFunctions } from 'vue-template-compiler'
 import { attrsSupported } from '~resources/test-utils'
-import { describeWithShallowAndMount } from '~resources/test-utils'
+import {
+  describeWithMountingMethods,
+  itSkipIf
+ } from '~resources/test-utils'
 
-describeWithShallowAndMount('options.attrs', (mountingMethod) => {
-  it('handles inherit attrs', () => {
+describeWithMountingMethods('options.attrs', (mountingMethod) => {
+  itSkipIf(mountingMethod.name === 'renderToString',
+  'handles inherit attrs', () => {
     if (!attrsSupported()) return
     const wrapper = mountingMethod(compileToFunctions('<p :id="anAttr" />'), {
       attrs: {
@@ -15,7 +19,8 @@ describeWithShallowAndMount('options.attrs', (mountingMethod) => {
     expect(wrapper.vm.$attrs.anAttr).to.equal('an attribute')
   })
 
-  it('defines attrs as empty object even when not passed', () => {
+  itSkipIf(mountingMethod.name === 'renderToString',
+  'defines attrs as empty object even when not passed', () => {
     const wrapper = mountingMethod(compileToFunctions('<p />'))
     expect(wrapper.vm.$attrs).to.deep.equal({})
   })