diff options
Diffstat (limited to 'doc/development/fe_guide/style/vue.md')
| -rw-r--r-- | doc/development/fe_guide/style/vue.md | 292 |
1 files changed, 154 insertions, 138 deletions
diff --git a/doc/development/fe_guide/style/vue.md b/doc/development/fe_guide/style/vue.md index a21d7c4577b..a3ab1c1af30 100644 --- a/doc/development/fe_guide/style/vue.md +++ b/doc/development/fe_guide/style/vue.md @@ -59,63 +59,66 @@ Check the [rules](https://github.com/vuejs/eslint-plugin-vue#bulb-rules) for mor 1. Explicitly define data being passed into the Vue app - ```javascript - // bad - return new Vue({ - el: '#element', - 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', - 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](../vuex.md#why-not-just-spread-the-initial-state). - The pattern above also enables us to easily parse non scalar values during - instantiation. - - ```javascript - return new Vue({ - el: '#element', - components: { - componentName - }, - props: { - foo, - bar: parseBoolean(bar) - }, - render: createElement => createElement('component-name'), - })); - ``` + ```javascript + // 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](../vuex.md#why-not-just-spread-the-initial-state). + The pattern above also enables us to easily parse non scalar values during + instantiation. + + ```javascript + return new Vue({ + el: '#element', + name: 'ComponentNameRoot', + components: { + componentName + }, + props: { + foo, + bar: parseBoolean(bar) + }, + render: createElement => createElement('component-name'), + })); + ``` ## Naming @@ -404,7 +407,7 @@ When using `v-for` you need to provide a *unique* `:key` attribute for each item ``` 1. When using `v-for` with `template` and there is more than one child element, the `:key` values -must be unique. It's advised to use `kebab-case` namespaces. + must be unique. It's advised to use `kebab-case` namespaces. ```html <template v-for="(item, index) in items"> @@ -467,8 +470,9 @@ Creating a global, mutable wrapper provides a number of advantages, including th ``` - Use a `beforeEach` block to mount the component (see -[the `createComponent` factory](#the-createcomponent-factory) for more information). -- Use an `afterEach` block to destroy the component, for example, `wrapper.destroy()`. + [the `createComponent` factory](#the-createcomponent-factory) for more information). +- Automatically destroy the component after the test is run with [`enableAutoDestroy`](https://v1.test-utils.vuejs.org/api/#enableautodestroy-hook) + set in [`shared_test_setup.js`](https://gitlab.com/gitlab-org/gitlab/-/blob/d0bdc8370ef17891fd718a4578e41fef97cf065d/spec/frontend/__helpers__/shared_test_setup.js#L20). #### The `createComponent` factory @@ -538,42 +542,42 @@ describe('MyComponent', () => { #### `createComponent` best practices 1. 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](javascript.md#limit-number-of-parameters) and - stay within the parameter number limit: + Defining single parameters for common data like `props` is okay, + but keep in mind our [JavaScript style guide](javascript.md#limit-number-of-parameters) and + stay within the parameter number limit: - ```javascript - // bad - function createComponent(data, props, methods, isLoading, mountFn) { } + ```javascript + // bad + function createComponent(data, props, methods, isLoading, mountFn) { } - // good - function createComponent({ data, props, methods, stubs, isLoading } = {}) { } + // good + function createComponent({ data, props, methods, stubs, isLoading } = {}) { } - // good - function createComponent(props = {}, { data, methods, stubs, isLoading } = {}) { } - ``` + // good + function createComponent(props = {}, { data, methods, stubs, isLoading } = {}) { } + ``` 1. If you require both `mount` _and_ `shallowMount` within the same set of tests, it -can be useful define a `mountFn` parameter for the `createComponent` factory that accepts -the mounting function (`mount` or `shallowMount`) to be used to mount the component: + can be useful define a `mountFn` parameter for the `createComponent` factory that accepts + the mounting function (`mount` or `shallowMount`) to be used to mount the component: - ```javascript - import { shallowMount } from '@vue/test-utils'; + ```javascript + import { shallowMount } from '@vue/test-utils'; - function createComponent({ mountFn = shallowMount } = {}) { } - ``` + function createComponent({ mountFn = shallowMount } = {}) { } + ``` 1. Use the `mountExtended` and `shallowMountExtended` helpers to expose `wrapper.findByTestId()`: - ```javascript - import { shallowMountExtended } from 'helpers/vue_test_utils_helper'; - import { SomeComponent } from 'components/some_component.vue'; + ```javascript + import { shallowMountExtended } from 'helpers/vue_test_utils_helper'; + import { SomeComponent } from 'components/some_component.vue'; - let wrapper; + let wrapper; - const createWrapper = () => { wrapper = shallowMountExtended(SomeComponent); }; - const someButton = () => wrapper.findByTestId('someButtonTestId'); - ``` + const createWrapper = () => { wrapper = shallowMountExtended(SomeComponent); }; + const someButton = () => wrapper.findByTestId('someButtonTestId'); + ``` ### Setting component state @@ -581,70 +585,82 @@ the mounting function (`mount` or `shallowMount`) to be used to mount the compon component state wherever possible. Instead, set the component's [`propsData`](https://v1.test-utils.vuejs.org/api/options.html#propsdata) when mounting the component: - ```javascript - // bad - wrapper = shallowMount(MyComponent); - wrapper.setProps({ - myProp: 'my cool prop' - }); + ```javascript + // bad + wrapper = shallowMount(MyComponent); + wrapper.setProps({ + myProp: 'my cool prop' + }); - // good - wrapper = shallowMount({ propsData: { 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. + 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. ### Accessing component state 1. When accessing props or attributes, prefer the `wrapper.props('myProp')` syntax over `wrapper.props().myProp` or `wrapper.vm.myProp`: - ```javascript - // good - expect(wrapper.props().myProp).toBe(true); - expect(wrapper.attributes().myAttr).toBe(true); + ```javascript + // 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); - ``` + // better + expect(wrapper.props('myProp').toBe(true); + expect(wrapper.attributes('myAttr')).toBe(true); + ``` 1. When asserting multiple props, check the deep equality of the `props()` object with [`toEqual`](https://jestjs.io/docs/expect#toequalvalue): - ```javascript - // 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', - }); - ``` + ```javascript + // 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', + }); + ``` 1. If you are only interested in some of the props, you can use [`toMatchObject`](https://jestjs.io/docs/expect#tomatchobjectobject). Prefer `toMatchObject` over [`expect.objectContaining`](https://jestjs.io/docs/expect#expectobjectcontainingobject): - ```javascript - // good - expect(wrapper.props()).toEqual(expect.objectContaining({ - propA: 'valueA', - propB: 'valueB', - })); + ```javascript + // good + expect(wrapper.props()).toEqual(expect.objectContaining({ + propA: 'valueA', + propB: 'valueB', + })); + + // better + expect(wrapper.props()).toMatchObject({ + propA: 'valueA', + propB: 'valueB', + }); + ``` + +### Testing props validation + +1. When checking component props use `assertProps` helper. Props validation failures will be thrown as errors - // better - expect(wrapper.props()).toMatchObject({ - propA: 'valueA', - propB: 'valueB', - }); - ``` +```javascript +import { assertProps } from 'helpers/assert_props' + +// ... + +expect(() => assertProps(SomeComponent, { invalidPropValue: '1', someOtherProp: 2 })).toThrow() +``` ## The JavaScript/Vue Accord @@ -659,16 +675,16 @@ The goal of this accord is to make sure we are all on the same page. 1. 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](https://v2.vuejs.org/v2/api/#vm-emit). 1. 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. + specific data (for example, `scrollTo` is ok to access anytime). Do this access during the + bootstrapping of your application. 1. 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. + 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. 1. 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. + not be rewritten. For example, jQuery tests rewritten to Vue tests. 1. 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](https://v2.vuejs.org/v2/guide/state-management.html#Simple-State-Management-from-Scratch). + must use the *store pattern* which can be found in the + [Vue.js documentation](https://v2.vuejs.org/v2/guide/state-management.html#Simple-State-Management-from-Scratch). 1. 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. + application. Don't mix and match your state-management solutions. |