Merge branch 'master' into next

Author: nogic1008

.gitignore

@@ -25,3 +25,5 @@ pids
 *.pid.lock
 
 package-lock.json
+/e2e/**/yarn.lock
+

README.md

@@ -1,10 +1,233 @@
-# vue-jest-next
+# vue-jest
 
-Jest Vue transformer for Vue 3 with source map support (WIP).
+Jest transformer for Vue single file components
 
-Docs for current stable version (targeting Vue 2.x): https://github.com/vuejs/vue-jest/
+> **NOTE:** This is documentation for `vue-jest@4.x`. [View the vue-jest@3.x documentation](https://github.com/vuejs/vue-jest/tree/v3)
 
-## TODO (supported in vue-jest@4.x but not vue-jest@next):
+## Usage
 
-- [ ] Support loading styles
-- [ ] Support custom blocks
+```bash
+npm install --save-dev vue-jest
+yarn add vue-jest --dev
+```
+
+### Usage with Babel 7
+
+If you use [jest](https://github.com/facebook/jest) > 24.0.0 and [babel-jest](https://github.com/facebook/jest/tree/master/packages/babel-jest) make sure to install babel-core@bridge
+
+```bash
+npm install --save-dev babel-core@bridge
+yarn add babel-core@bridge --dev
+```
+
+## Setup
+
+To use `vue-jest` as a transformer for your `.vue` files, map them to the `vue-jest` module:
+
+```json
+{
+  "jest": {
+    "transform": {
+      "^.+\\.vue$": "vue-jest"
+    }
+  }
+}
+```
+
+A full config will look like this.
+
+```json
+{
+  "jest": {
+    "moduleFileExtensions": ["js", "json", "vue"],
+    "transform": {
+      "^.+\\.js$": "babel-jest",
+      "^.+\\.vue$": "vue-jest"
+    }
+  }
+}
+```
+
+## Examples
+
+Example repositories testing Vue components with jest and vue-jest:
+
+- [Vue Test Utils with Jest](https://github.com/eddyerburgh/vue-test-utils-jest-example)
+
+## Supported langs
+
+vue-jest compiles `<script />`, `<template />`, and `<style />` blocks with supported `lang` attributes into JavaScript that Jest can run.
+
+### Supported script languages
+
+- **typescript** (`lang="ts"`, `lang="typescript"`)
+- **coffeescript** (`lang="coffee"`, `lang="coffeescript"`)
+
+### Global Jest options
+
+You can change the behavior of `vue-jest` by using `jest.globals`.
+
+#### Supporting custom blocks
+
+A great feature of the Vue SFC compiler is that it can support custom blocks. You might want to use those blocks in your tests. To render out custom blocks for testing purposes, you'll need to write a transformer. Once you have your transformer, you'll add an entry to vue-jest's transform map. This is how [vue-i18n's](https://github.com/kazupon/vue-i18n) `<i18n>` custom blocks are supported in unit tests.
+
+A `package.json` Example
+
+```json
+{
+  "jest": {
+    "moduleFileExtensions": ["js", "json", "vue"],
+    "transform": {
+      "^.+\\.js$": "babel-jest",
+      "^.+\\.vue$": "vue-jest"
+    },
+    "globals": {
+      "vue-jest": {
+        "transform": {
+          "your-custom-block": "./custom-block-processor.js"
+        }
+      }
+    }
+  }
+}
+```
+
+> _Tip:_ Need programmatic configuration? Use the [--config](https://jestjs.io/docs/en/cli.html#config-path) option in Jest CLI, and export a `.js` file
+
+A `jest.config.js` Example - If you're using a dedicated configuration file like you can reference and require your processor in the config file instead of using a file reference.
+
+```js
+module.exports = {
+  globals: {
+    'vue-jest': {
+      transform: {
+        'your-custom-block': require('./custom-block-processor')
+      }
+    }
+  }
+}
+```
+
+#### Writing a processor
+
+Processors must return an object with a "process" method, like so...
+
+```js
+module.exports = {
+  /**
+   * Process the content inside of a custom block and prepare it for execution in a testing environment
+   * @param {SFCCustomBlock[]} blocks All of the blocks matching your type, returned from `@vue/component-compiler-utils`
+   * @param {string} vueOptionsNamespace The internal namespace for a component's Vue Options in vue-jest
+   * @param {string} filename The SFC file being processed
+   * @param {Object} config The full Jest config
+   * @returns {string} The code to be output after processing all of the blocks matched by this type
+   */
+  process({ blocks, vueOptionsNamespace, filename, config }) {}
+}
+```
+
+#### templateCompiler
+
+You can provide [TemplateCompileOptions](https://github.com/vuejs/component-compiler-utils#compiletemplatetemplatecompileoptions-templatecompileresults) in `templateCompiler` section like this:
+
+```json
+{
+  "jest": {
+    "globals": {
+      "vue-jest": {
+        "templateCompiler": {
+          "transpileOptions": {
+            "transforms": {
+              "dangerousTaggedTemplateString": true
+            }
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+### Supported template languages
+
+- **pug** (`lang="pug"`)
+
+  - To give options for the Pug compiler, enter them into the Jest configuration.
+    The options will be passed to pug.compile().
+
+  ```json
+  {
+    "jest": {
+      "globals": {
+        "vue-jest": {
+          "pug": {
+            "basedir": "mybasedir"
+          }
+        }
+      }
+    }
+  }
+  ```
+
+- **jade** (`lang="jade"`)
+- **haml** (`lang="haml"`)
+
+### Supported style languages
+
+- **stylus** (`lang="stylus"`, `lang="styl"`)
+- **sass** (`lang="sass"`), and
+- **scss** (`lang="scss"`)
+
+  - The Sass compiler supports Jest's [moduleNameMapper](https://facebook.github.io/jest/docs/en/configuration.html#modulenamemapper-object-string-string) which is the suggested way of dealing with Webpack aliases. Webpack's `sass-loader` uses a [special syntax](https://github.com/webpack-contrib/sass-loader/blob/v9.0.2/README.md#resolving-import-at-rules) for indicating non-relative imports, so you'll likely need to copy this syntax into your `moduleNameMapper` entries if you make use of it. For aliases of bare imports (imports that require node module resolution), the aliased value must also be prepended with this `~` or `vue-jest`'s custom resolver won't recognize it.
+    ```json
+    {
+      "jest": {
+        "moduleNameMapper": {
+          "^~foo/(.*)": "<rootDir>/foo/$1",
+          // @import '~foo'; -> @import 'path/to/project/foo';
+          "^~bar/(.*)": "~baz/lib/$1"
+          // @import '~bar/qux'; -> @import 'path/to/project/node_modules/baz/lib/qux';
+          // Notice how the tilde (~) was needed on the bare import to baz.
+        }
+      }
+    }
+    ```
+  - To import globally included files (ie. variables, mixins, etc.), include them in the Jest configuration at `jest.globals['vue-jest'].resources.scss`:
+
+    ```json
+    {
+      "jest": {
+        "globals": {
+          "vue-jest": {
+            "resources": {
+              "scss": [
+                "./node_modules/package/_mixins.scss",
+                "./src/assets/css/globals.scss"
+              ]
+            }
+          }
+        }
+      }
+    }
+    ```
+
+## CSS options
+
+`experimentalCSSCompile`: `Boolean` Default true. Turn off CSS compilation
+
+`hideStyleWarn`: `Boolean` Default false. Hide warnings about CSS compilation
+
+`resources`:
+
+```json
+{
+  "jest": {
+    "globals": {
+      "vue-jest": {
+        "hideStyleWarn": true,
+        "experimentalCSSCompile": true
+      }
+    }
+  }
+}
+```

e2e/2.x/babel-in-package/components/Basic.vue

@@ -0,0 +1,47 @@
+<template>
+  <div class="hello">
+    <h1 :class="headingClasses">{{ msg }}</h1>
+  </div>
+</template>
+
+<style module="css">
+.testA {
+  background-color: red;
+}
+</style>
+<style module>
+.testB {
+  background-color: blue;
+}
+</style>
+<style>
+.testC {
+  background-color: blue;
+}
+</style>
+
+<script>
+export default {
+  name: 'basic',
+  computed: {
+    headingClasses: function headingClasses() {
+      return {
+        red: this.isCrazy,
+        blue: !this.isCrazy,
+        shadow: this.isCrazy
+      }
+    }
+  },
+  data: function data() {
+    return {
+      msg: 'Welcome to Your Vue.js App',
+      isCrazy: false
+    }
+  },
+  methods: {
+    toggleClass: function toggleClass() {
+      this.isCrazy = !this.isCrazy
+    }
+  }
+}
+</script>

e2e/2.x/babel-in-package/components/Coffee.vue

@@ -0,0 +1,8 @@
+<template>
+  <div />
+</template>
+
+<script lang="coffee">
+export default
+    data: -> {}
+</script>

e2e/2.x/babel-in-package/components/TypeScript.vue

@@ -0,0 +1,21 @@
+<template>
+  <div>
+    {{ exclamationMarks }}
+    <type-script-child />
+  </div>
+</template>
+
+<script lang="ts">
+import TypeScriptChild from './TypeScriptChild.vue'
+
+export default {
+  computed: {
+    exclamationMarks(): string {
+      return 'string'
+    }
+  },
+  components: {
+    TypeScriptChild
+  }
+}
+</script>

e2e/2.x/babel-in-package/components/TypeScriptChild.vue

@@ -0,0 +1,13 @@
+<template>
+  <div>{{ exclamationMarks }}</div>
+</template>
+
+<script lang="ts">
+export default {
+  computed: {
+    exclamationMarks(): string {
+      return 'string'
+    }
+  }
+}
+</script>

e2e/2.x/babel-in-package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "vue2-babel-in-package",
+  "version": "1.0.0",
+  "license": "MIT",
+  "private": true,
+  "scripts": {
+    "test": "jest --no-cache test.js"
+  },
+  "dependencies": {
+    "source-map": "0.5.6",
+    "vue": "^2.5.21",
+    "vue-template-compiler": "^2.5.21"
+  },
+  "devDependencies": {
+    "@babel/core": "^7.9.0",
+    "@babel/preset-env": "^7.9.0",
+    "@vue/test-utils": "^1.1.0",
+    "coffeescript": "^2.3.2",
+    "jest": "26.x",
+    "ts-jest": "^26.3.0",
+    "typescript": "^3.2.2",
+    "vue2-jest": "~26.0.0"
+  },
+  "jest": {
+    "moduleFileExtensions": [
+      "js",
+      "json",
+      "vue"
+    ],
+    "transform": {
+      "^.+\\.js$": "babel-jest",
+      "^.+\\.vue$": "vue2-jest"
+    }
+  },
+  "babel": {
+    "presets": [
+      "@babel/env"
+    ]
+  }
+}

e2e/2.x/babel-in-package/test.js

@@ -0,0 +1,19 @@
+import { mount } from '@vue/test-utils'
+import TypeScript from './components/TypeScript.vue'
+import Basic from './components/Basic.vue'
+import Coffee from './components/Coffee.vue'
+
+test('processes .vue files', () => {
+  const wrapper = mount(Basic)
+  wrapper.vm.toggleClass()
+})
+
+test('processes .vue file with lang set to coffee', () => {
+  const wrapper = mount(Coffee)
+  expect(wrapper.vm).toBeTruthy()
+})
+
+test('processes .vue files with lang set to typescript', () => {
+  const wrapper = mount(TypeScript)
+  expect(wrapper.vm).toBeTruthy()
+})