- Linting
- Basic Rules
- Naming
- Alignment
- Quotes
- Props
- Data
- Directives
- Closing tags
- Component usage within templates
- Ordering
:key
- Vue testing
- The JavaScript/Vue Accord
Vue.js style guide
Linting
We default to eslint-vue-plugin, with the plugin:vue/recommended
.
Check the rules for more documentation.
Basic Rules
- The service has its own file
- The store has its own file
-
Use a function in the bundle file to instantiate the Vue component:
// bad class { init() { new Component({}) } } // good document.addEventListener('DOMContentLoaded', () => new Vue({ el: '#element', components: { componentName }, render: createElement => createElement('component-name'), }));
-
Do not use a singleton for the service or the store
// bad class Store { constructor() { if (!this.prototype.singleton) { // do something } } } // good class Store { constructor() { // do something } }
-
Use
.vue
for Vue templates. Do not use%template
in HAML. -
Explicitly define data being passed into the Vue app
// bad return new Vue({ el: '#element', name: 'ComponentNameRoot', components: { componentName }, provide: { ...someDataset }, props: { ...anotherDataset }, render: createElement => createElement('component-name'), })); // good const { foobar, barfoo } = someDataset; const { foo, bar } = anotherDataset; return new Vue({ el: '#element', name: 'ComponentNameRoot', components: { componentName }, provide: { foobar, barfoo }, props: { foo, bar }, render: createElement => createElement('component-name'), }));
We discourage the use of the spread operator in this specific case in order to keep our codebase explicit, discoverable, and searchable. This applies in any place where we would benefit from the above, such as when initializing Vuex state. The pattern above also enables us to easily parse non scalar values during instantiation.
return new Vue({ el: '#element', name: 'ComponentNameRoot', components: { componentName }, props: { foo, bar: parseBoolean(bar) }, render: createElement => createElement('component-name'), }));
Naming
-
Extensions: Use
.vue
extension for Vue components. Do not use.js
as file extension (#34371). -
Reference Naming: Use PascalCase for their default imports:
// bad import cardBoard from 'cardBoard.vue' components: { cardBoard, }; // good import CardBoard from 'cardBoard.vue' components: { CardBoard, };
- Props Naming: Avoid using DOM component prop names.
-
Props Naming: Use kebab-case instead of camelCase to provide props in templates.
// bad <component class="btn"> // good <component css-class="btn"> // bad <component myProp="prop" /> // good <component my-prop="prop" />
Alignment
-
Follow these alignment styles for the template method:
-
With more than one attribute, all attributes should be on a new line:
// bad <component v-if="bar" param="baz" /> <button class="btn">Click me</button> // good <component v-if="bar" param="baz" /> <button class="btn"> Click me </button>
-
The tag can be inline if there is only one attribute:
// good <component bar="bar" /> // good <component bar="bar" /> // bad <component bar="bar" />
-
Quotes
-
Always use double quotes
"
inside templates and single quotes'
for all other JS.// bad template: ` <button :class='style'>Button</button> ` // good template: ` <button :class="style">Button</button> `
Props
-
Props should be declared as an object
// bad props: ['foo'] // good props: { foo: { type: String, required: false, default: 'bar' } }
-
Required key should always be provided when declaring a prop
// bad props: { foo: { type: String, } } // good props: { foo: { type: String, required: false, default: 'bar' } }
-
Default key should be provided if the prop is not required. There are some scenarios where we need to check for the existence of the property. On those a default key should not be provided.
// good props: { foo: { type: String, required: false, } } // good props: { foo: { type: String, required: false, default: 'bar' } } // good props: { foo: { type: String, required: true } }
Data
-
data
method should always be a function// bad data: { foo: 'foo' } // good data() { return { foo: 'foo' }; }
Directives
-
Shorthand
@
is preferable overv-on
// bad <component v-on:click="eventHandler"/> // good <component @click="eventHandler"/>
-
Shorthand
:
is preferable overv-bind
// bad <component v-bind:class="btn"/> // good <component :class="btn"/>
-
Shorthand
#
is preferable overv-slot
// bad <template v-slot:header></template> // good <template #header></template>
Closing tags
-
Prefer self-closing component tags
// bad <component></component> // good <component />
Component usage within templates
-
Prefer a component’s kebab-cased name over other styles when using it in a template
// bad <MyComponent /> // good <my-component />
Ordering
-
Tag order in
.vue
file<script> // ... </script> <template> // ... </template> // We don't use scoped styles but there are few instances of this <style> // ... </style>
-
Properties in a Vue Component: Check order of properties in components rule.
:key
When using v-for
you need to provide a unique :key
attribute for each item.
-
If the elements of the array being iterated have an unique
id
it is advised to use it:<div v-for="item in items" :key="item.id" > <!-- content --> </div>
-
When the elements being iterated don’t have a unique ID, you can use the array index as the
:key
attribute<div v-for="(item, index) in items" :key="index" > <!-- content --> </div>
-
When using
v-for
withtemplate
and there is more than one child element, the:key
values must be unique. It’s advised to usekebab-case
namespaces.<template v-for="(item, index) in items"> <span :key="`span-${index}`"></span> <button :key="`button-${index}`"></button> </template>
-
When dealing with nested
v-for
use the same guidelines as above.<div v-for="item in items" :key="item.id" > <span v-for="element in array" :key="element.id" > <!-- content --> </span> </div>
Useful links:
Vue testing
Over time, a number of programming patterns and style preferences have emerged in our efforts to effectively test Vue components. The following guide describes some of these. These are not strict guidelines, but rather a collection of suggestions and good practices that aim to provide insight into how we write Vue tests at GitLab.
Mounting a component
Typically, when testing a Vue component, the component should be “re-mounted” in every test block.
To achieve this:
- Create a mutable
wrapper
variable inside the top-leveldescribe
block. - Mount the component using
mount
orshallowMount
. - Reassign the resulting
Wrapper
instance to ourwrapper
variable.
Creating a global, mutable wrapper provides a number of advantages, including the ability to:
-
Define common functions for finding components/DOM elements:
import MyComponent from '~/path/to/my_component.vue'; describe('MyComponent', () => { let wrapper; // this can now be reused across tests const findMyComponent = wrapper.findComponent(MyComponent); // ... })
- Use a
beforeEach
block to mount the component (see thecreateComponent
factory for more information). - Automatically destroy the component after the test is run with
enableAutoDestroy
set inshared_test_setup.js
.
Async child components
shallowMount
will not create component stubs for async child components. In order to properly stub async child components, use the stubs
option. Make sure the async child component has a name
option defined, otherwise your wrapper
’s findComponent
method may not work correctly.
The createComponent
factory
To avoid duplicating our mounting logic, it’s useful to define a createComponent
factory function
that we can reuse in each test block. This is a closure which should reassign our wrapper
variable
to the result of mount
and
shallowMount
:
import MyComponent from '~/path/to/my_component.vue';
import { shallowMount } from '@vue/test-utils';
describe('MyComponent', () => {
// Initiate the "global" wrapper variable. This will be used throughout our test:
let wrapper;
// Define our `createComponent` factory:
function createComponent() {
// Mount component and reassign `wrapper`:
wrapper = shallowMount(MyComponent);
}
it('mounts', () => {
createComponent();
expect(wrapper.exists()).toBe(true);
});
it('`isLoading` prop defaults to `false`', () => {
createComponent();
expect(wrapper.props('isLoading')).toBe(false);
});
})
Similarly, we could further de-duplicate our test by calling createComponent
in a beforeEach
block:
import MyComponent from '~/path/to/my_component.vue';
import { shallowMount } from '@vue/test-utils';
describe('MyComponent', () => {
// Initiate the "global" wrapper variable. This will be used throughout our test
let wrapper;
// define our `createComponent` factory
function createComponent() {
// mount component and reassign `wrapper`
wrapper = shallowMount(MyComponent);
}
beforeEach(() => {
createComponent();
});
it('mounts', () => {
expect(wrapper.exists()).toBe(true);
});
it('`isLoading` prop defaults to `false`', () => {
expect(wrapper.props('isLoading')).toBe(false);
});
})
createComponent
best practices
-
Consider using a single (or a limited number of) object arguments over many arguments. Defining single parameters for common data like
props
is okay, but keep in mind our JavaScript style guide and stay within the parameter number limit:// bad function createComponent(props, stubs, mountFn, foo) { } // good function createComponent({ props, stubs, mountFn, foo } = {}) { } // good function createComponent(props = {}, { stubs, mountFn, foo } = {}) { }
-
If you require both
mount
andshallowMount
within the same set of tests, it can be useful define amountFn
parameter for thecreateComponent
factory that accepts the mounting function (mount
orshallowMount
) to be used to mount the component:import { shallowMount } from '@vue/test-utils'; function createComponent({ mountFn = shallowMount } = {}) { }
-
Use the
mountExtended
andshallowMountExtended
helpers to exposewrapper.findByTestId()
:import { shallowMountExtended } from 'helpers/vue_test_utils_helper'; import { SomeComponent } from 'components/some_component.vue'; let wrapper; const createWrapper = () => { wrapper = shallowMountExtended(SomeComponent); }; const someButton = () => wrapper.findByTestId('someButtonTestId');
-
Avoid using
data
,methods
, or any other mounting option that extends component internals.
import { shallowMountExtended } from 'helpers/vue_test_utils_helper';
import { SomeComponent } from 'components/some_component.vue';
let wrapper;
// bad :( - This circumvents the actual user interaction and couples the test to component internals.
const createWrapper = ({ data }) => {
wrapper = shallowMountExtended(SomeComponent, {
data
});
};
// good :) - Helpers like `clickShowButton` interact with the actual I/O of the component.
const createWrapper = () => {
wrapper = shallowMountExtended(SomeComponent);
};
const clickShowButton = () => {
wrapper.findByTestId('show').trigger('click');
}
Setting component state
-
Avoid using
setProps
to set component state wherever possible. Instead, set the component’spropsData
when mounting the component:// bad wrapper = shallowMount(MyComponent); wrapper.setProps({ myProp: 'my cool prop' }); // good wrapper = shallowMount({ propsData: { myProp: 'my cool prop' } });
The exception here is when you wish to test component reactivity in some way. For example, you may want to test the output of a component when after a particular watcher has executed. Using
setProps
to test such behavior is okay. -
Avoid using
setData
which sets the component’s internal state and circumvents testing the actual I/O of the component. Instead, trigger events on the component’s children or other side-effects to force state changes.
Accessing component state
-
When accessing props or attributes, prefer the
wrapper.props('myProp')
syntax overwrapper.props().myProp
orwrapper.vm.myProp
:// good expect(wrapper.props().myProp).toBe(true); expect(wrapper.attributes().myAttr).toBe(true); // better expect(wrapper.props('myProp').toBe(true); expect(wrapper.attributes('myAttr')).toBe(true);
-
When asserting multiple props, check the deep equality of the
props()
object withtoEqual
:// good expect(wrapper.props('propA')).toBe('valueA'); expect(wrapper.props('propB')).toBe('valueB'); expect(wrapper.props('propC')).toBe('valueC'); // better expect(wrapper.props()).toEqual({ propA: 'valueA', propB: 'valueB', propC: 'valueC', });
-
If you are only interested in some of the props, you can use
toMatchObject
. PrefertoMatchObject
overexpect.objectContaining
:// good expect(wrapper.props()).toEqual(expect.objectContaining({ propA: 'valueA', propB: 'valueB', })); // better expect(wrapper.props()).toMatchObject({ propA: 'valueA', propB: 'valueB', });
Testing props validation
When checking component props use assertProps
helper. Props validation failures will be thrown as errors:
import { assertProps } from 'helpers/assert_props'
// ...
expect(() => assertProps(SomeComponent, { invalidPropValue: '1', someOtherProp: 2 })).toThrow()
The JavaScript/Vue Accord
The goal of this accord is to make sure we are all on the same page.
- When writing Vue, you may not use jQuery in your application.
- If you need to grab data from the DOM, you may query the DOM 1 time while bootstrapping your
application to grab data attributes using
dataset
. You can do this without jQuery. - You may use a jQuery dependency in Vue.js following this example from the docs.
- If an outside jQuery Event needs to be listen to inside the Vue application, you may use jQuery event listeners.
- We avoid adding new jQuery events when they are not required. Instead of adding new jQuery events take a look at different methods to do the same task.
- If you need to grab data from the DOM, you may query the DOM 1 time while bootstrapping your
application to grab data attributes using
- You may query the
window
object one time, while bootstrapping your application for application specific data (for example,scrollTo
is ok to access anytime). Do this access during the bootstrapping of your application. - You may have a temporary but immediate need to create technical debt by writing code that does not follow our standards, to be refactored later. Maintainers need to be ok with the tech debt in the first place. An issue should be created for that tech debt to evaluate it further and discuss. In the coming months you should fix that tech debt, with its priority to be determined by maintainers.
- When creating tech debt you must write the tests for that code before hand and those tests may not be rewritten. For example, jQuery tests rewritten to Vue tests.
- You may choose to use VueX as a centralized state management. If you choose not to use VueX, you must use the store pattern which can be found in the Vue.js documentation.
- Once you have chosen a centralized state-management solution you must use it for your entire application. Don’t mix and match your state-management solutions.