Skip to content

docs: update README #140

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 2 commits into from
Closed

docs: update README #140

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
4197cc1
docs: update README
eddyerburgh Jan 5, 2019
49a6061
docs: add link to v3 docs
eddyerburgh Jan 5, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
228 changes: 43 additions & 185 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,8 +1,8 @@
# vue-jest

Jest Vue transformer with source map support
Jest transformer for Vue single file components

> **NOTE:** This is documentation for `[email protected]`. [View the [email protected] documentation](https://github.com/vuejs/vue-jest/tree/e694fc7ce11ae1ac1c778ed7c4402515c5f0d5aa)
_Note: These are the docs for v4—for older documentation [see the v3 docs](https://github.com/vuejs/vue-jest/tree/v3)_

## Usage

Expand All @@ -12,9 +12,9 @@ npm install --save-dev vue-jest

## Setup

To define `vue-jest` as a transformer for your `.vue` files, map them to the `vue-jest` module:
To use `vue-jest` as a transformer for your `.vue` files, map them to the `vue-jest` module:

```json
```js
{
"jest": {
"transform": {
Expand All @@ -23,9 +23,9 @@ To define `vue-jest` as a transformer for your `.vue` files, map them to the `vu
}
```

A full config will look like this.
A full config might look like this:

```json
```js
{
"jest": {
"moduleFileExtensions": ["js", "json", "vue"],
Expand All @@ -37,210 +37,52 @@ A full config will look like this.
}
```

If you're on a version of Jest older than 22.4.0, you need to set `mapCoverage` to `true` in order to use source maps.

## Example Projects

Example repositories testing Vue components with jest and vue-jest:
## Examples

- [Avoriaz with Jest](https://github.com/eddyerburgh/avoriaz-jest-example)
- [Vue Test Utils with Jest](https://github.com/eddyerburgh/vue-test-utils-jest-example)

## Supported langs

vue-jest compiles the script and template of SFCs into a JavaScript file that Jest can run. **Currently, SCSS, SASS and Stylus are the only style languages that are compiled**.

### 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`.

> _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

#### babelConfig

Provide `babelConfig` in one of the following formats:

- `<Boolean>`
- `<Object>`
- `<String>`

##### Boolean

- `true` - Enable Babel processing. `vue-jest` will try to find Babel configuration using [find-babel-config](https://www.npmjs.com/package/find-babel-config).

> This is the default behavior if [babelConfig](#babelconfig) is not defined.

- `false` - Skip Babel processing entirely:

```json
{
"jest": {
"globals": {
"vue-jest": {
"babelConfig": false
}
}
}
}
```

##### Object

Provide inline [Babel options](https://babeljs.io/docs/en/options):

```json
{
"jest": {
"globals": {
"vue-jest": {
"babelConfig": {
"presets": [
[
"env",
{
"useBuiltIns": "entry",
"shippedProposals": true
}
]
],
"plugins": ["syntax-dynamic-import"],
"env": {
"test": {
"plugins": ["dynamic-import-node"]
}
}
}
}
}
}
}
```

##### String

If a string is provided, it will be an assumed path to a babel configuration file (e.g. `.babelrc`, `.babelrc.js`).

- Config file should export a Babel configuration object.
- Should _not_ point to a [project-wide configuration file (babel.config.js)](https://babeljs.io/docs/en/config-files#project-wide-configuration), which exports a function.

```json
{
"jest": {
"globals": {
"vue-jest": {
"babelConfig": "path/to/.babelrc.js"
}
}
}
}
```

To use the [Config Function API](https://babeljs.io/docs/en/config-files#config-function-api), use inline options instead. i.e.:
vue-jest compiles `<script />`, `<template />`, and `<style />` blocks with supported `lang` attributes into JavaScript that Jest can run.

```json
{
"jest": {
"globals": {
"vue-jest": {
"babelConfig": {
"configFile": "path/to/babel.config.js"
}
}
}
}
}
```

#### tsConfig

Provide `tsConfig` in one of the following formats:
### Script languages

- `<Boolean>`
- `<Object>`
- `<String>`
- **TypeScript** (`ts`, `typescript`)
- **CoffeeScript** (`coffee`, `coffeescript`)

##### Boolean
### Template languages

- `true` - Process TypeScript files using custom configuration. `vue-jest` will try to find TypeScript configuration using [tsconfig.loadSync](https://www.npmjs.com/package/tsconfig#api).
vue-jest uses [consolidate](https://github.com/tj/consolidate.js/) to compile template languages. See the list of [supported engines](https://github.com/tj/consolidate.js/#supported-template-engines).

> This is the default behavior if [tsConfig](#tsConfig) is not defined.
_Note: engines that compile asynchronously are not supported_

- `false` - Process TypeScript files using the [default configuration provided by vue-jest](https://github.com/vuejs/vue-jest/blob/master/lib/load-typescript-config.js#L5-L27).
To pass options to the language compiler, add them to `jest.globals.vue-jest`:

##### Object

Provide inline [TypeScript compiler options](https://www.typescriptlang.org/docs/handbook/compiler-options.html):

```json
```js
{
"jest": {
"globals": {
"vue-jest": {
"tsConfig": {
"importHelpers": true
"pug": {
"basedir": "mybasedir"
}
}
}
}
}
```

##### String
### Style languages

If a string is provided, it will be an assumed path to a TypeScript configuration file:

```json
{
"jest": {
"globals": {
"vue-jest": {
"tsConfig": "path/to/tsconfig.json"
}
}
}
}
```

### 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"`)
- Stylus (`stylus`, `styl`)
- Sass (`sass`)
- 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.
- **scss** (`lang="scss"`)
- SCSS (`scss`)

- The SCSS 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.
- To import globally included files (ie. variables, mixins, etc.), include them in the Jest configuration at `jest.globals['vue-jest'].resources.scss`:

```json
```js
{
"jest": {
"globals": {
Expand All @@ -257,11 +99,17 @@ If a string is provided, it will be an assumed path to a TypeScript configuratio
}
```

## CSS options
## Configuration

You can configure vue-jest with `jest.globals`.

_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_

### options

`experimentalCSSCompile`: `Boolean` Default true. Turn off CSS compilation
`hideStyleWarn`: `Boolean` Default false. Hide warnings about CSS compilation
`resources`:
`experimentalCSSCompile`: `Boolean` Turn off CSS compilation (default `true`)

`hideStyleWarn`: `Boolean` Hide warnings about CSS compilation (default `false`)

```json
{
Expand All @@ -275,3 +123,13 @@ If a string is provided, it will be an assumed path to a TypeScript configuratio
}
}
```

### babel options

vue-jest uses babel-jest to resolve babel options.

### tsconfig

vue-jest uses ts-jest to resolve your `tsconfig` file.

If you wish to pass in a custom location for your tsconfig file, use the [ts-jest configuration options](https://kulshekhar.github.io/ts-jest/user/config/#options).