Add latest changes from gitlab-org/gitlab@13-4-stable-ee

5 files changed, 240 insertions, 13 deletions

diff --git a/doc/development/fe_guide/development_process.md b/doc/development/fe_guide/development_process.md
index ff36b8b5c6a..2b64534e7c9 100644
--- a/doc/development/fe_guide/development_process.md
+++ b/doc/development/fe_guide/development_process.md
@@ -4,7 +4,7 @@ You can find more about the organization of the frontend team in the [handbook](
 
 ## Development Checklist
 
-The idea is to remind us about specific topics during the time we build a new feature or start something. This is a common practice in other industries (like pilots) that also use standardised checklists to reduce problems early on.
+The idea is to remind us about specific topics during the time we build a new feature or start something. This is a common practice in other industries (like pilots) that also use standardized checklists to reduce problems early on.
 
 Copy the content over to your issue or merge request and if something doesn't apply simply remove it from your current list.
 
diff --git a/doc/development/fe_guide/frontend_faq.md b/doc/development/fe_guide/frontend_faq.md
index 71436a7c7fb..0a26fdba934 100644
--- a/doc/development/fe_guide/frontend_faq.md
+++ b/doc/development/fe_guide/frontend_faq.md
@@ -162,7 +162,7 @@ To return to the normal development mode:
 1. Open `gitlab.yaml` located in your `gitlab` installation folder, scroll down to the `webpack` section and change back `dev_server` to `enabled: true`.
 1. Run `yarn clean` to remove the production assets and free some space (optional).
 1. Start webpack again: `gdk start webpack`.
-1. Restart GDK: `gdk-restart rails-web`.
+1. Restart GDK: `gdk restart rails-web`.
 
 ### 8. Babel polyfills
 
diff --git a/doc/development/fe_guide/graphql.md b/doc/development/fe_guide/graphql.md
index f5e16d377f1..82cd19dce4f 100644
--- a/doc/development/fe_guide/graphql.md
+++ b/doc/development/fe_guide/graphql.md
@@ -1,3 +1,10 @@
+---
+type: reference, dev
+stage: none
+group: Development
+info: "See the Technical Writers assigned to Development Guidelines: https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments-to-development-guidelines"
+---
+
 # GraphQL
 
 ## Getting Started
@@ -32,6 +39,9 @@ can help you learn how to integrate Vue Apollo.
 
 For other use cases, check out the [Usage outside of Vue](#usage-outside-of-vue) section.
 
+We use [Immer](https://immerjs.github.io/immer/docs/introduction) for immutable cache updates;
+see [Immutability and cache updates](#immutability-and-cache-updates) for more information.
+
 ### Tooling
 
 - [Apollo Client Devtools](https://github.com/apollographql/apollo-client-devtools)
@@ -131,6 +141,56 @@ fragment DesignItem on Design {
 More about fragments:
 [GraphQL Docs](https://graphql.org/learn/queries/#fragments)
 
+## Global IDs
+
+GitLab's GraphQL API expresses `id` fields as Global IDs rather than the PostgreSQL
+primary key `id`. Global ID is [a convention](https://graphql.org/learn/global-object-identification/)
+used for caching and fetching in client-side libraries.
+
+To convert a Global ID to the primary key `id`, you can use `getIdFromGraphQLId`:
+
+```javascript
+import { getIdFromGraphQLId } from '~/graphql_shared/utils';
+
+const primaryKeyId = getIdFromGraphQLId(data.id);
+```
+
+## Immutability and cache updates
+
+From Apollo version 3.0.0 all the cache updates need to be immutable; it needs to be replaced entirely
+with a **new and updated** object.
+
+To facilitate the process of updating the cache and returning the new object we use the library [Immer](https://immerjs.github.io/immer/docs/introduction).
+When possible, follow these conventions:
+
+- The updated cache is named `data`.
+- The original cache data is named `sourceData`.
+
+A typical update process looks like this:
+
+```javascript
+...
+const sourceData = client.readQuery({ query });
+
+const data = produce(sourceData, draftState => {
+  draftState.commits.push(newCommit);
+});
+
+client.writeQuery({
+  query,
+  data,
+});
+...
+```
+
+As shown in the code example by using `produce`, we can perform any kind of direct manipulation of the
+`draftState`. Besides, `immer` guarantees that a new state which includes the changes to `draftState` will be generated.
+
+Finally, to verify whether the immutable cache update is working properly, we need to change
+`assumeImmutableResults` to `true` in the `default client config` (see [Apollo Client](#apollo-client) for more info). 
+
+If everything is working properly `assumeImmutableResults` should remain set to `true`.
+
 ## Usage in Vue
 
 To use Vue Apollo, import the [Vue Apollo](https://github.com/vuejs/vue-apollo) plugin as well
@@ -602,6 +662,174 @@ it('calls mutation on submitting form ', () => {
 });
 ```
 
+### Testing with mocked Apollo Client
+
+To test the logic of Apollo cache updates, we might want to mock an Apollo Client in our unit tests. To separate tests with mocked client from 'usual' unit tests, it's recommended to create an additional component factory. This way we only create Apollo Client instance when it's necessary:
+
+```javascript
+function createComponent() {...}
+
+function createComponentWithApollo() {...}
+```
+
+We use [`mock-apollo-client`](https://www.npmjs.com/package/mock-apollo-client) library to mock Apollo client in tests.
+
+```javascript
+import { createMockClient } from 'mock-apollo-client';
+```
+
+Then we need to inject `VueApollo` to Vue local instance (`localVue.use()` can also be called within `createComponentWithApollo()`)
+
+```javascript
+import VueApollo from 'vue-apollo';
+import { createLocalVue } from '@vue/test-utils';
+
+const localVue = createLocalVue();
+localVue.use(VueApollo);
+```
+
+After this, on the global `describe`, we should create a variable for `fakeApollo`:
+
+```javascript
+describe('Some component with Apollo mock', () => {
+  let wrapper;
+  let fakeApollo
+})
+```
+
+Within component factory, we need to define an array of _handlers_ for every query or mutation:
+
+```javascript
+import getDesignListQuery from '~/design_management/graphql/queries/get_design_list.query.graphql';
+import permissionsQuery from '~/design_management/graphql/queries/design_permissions.query.graphql';
+import moveDesignMutation from '~/design_management/graphql/mutations/move_design.mutation.graphql';
+
+describe('Some component with Apollo mock', () => {
+  let wrapper;
+  let fakeApollo;
+
+  function createComponentWithApollo() {
+    const requestHandlers = [
+      [getDesignListQuery, jest.fn().mockResolvedValue(designListQueryResponse)],
+      [permissionsQuery, jest.fn().mockResolvedValue(permissionsQueryResponse)],
+    ];
+  }
+})
+```
+
+After this, we need to create a mock Apollo Client instance using a helper:
+
+```javascript
+import createMockApollo from 'jest/helpers/mock_apollo_helper';
+
+describe('Some component with Apollo mock', () => {
+  let wrapper;
+  let fakeApollo;
+
+  function createComponentWithApollo() {
+    const requestHandlers = [
+      [getDesignListQuery, jest.fn().mockResolvedValue(designListQueryResponse)],
+      [permissionsQuery, jest.fn().mockResolvedValue(permissionsQueryResponse)],
+    ];
+
+    fakeApollo = createMockApollo(requestHandlers);
+    wrapper = shallowMount(Index, {
+      localVue,
+      apolloProvider: fakeApollo,
+    });
+  }
+})
+```
+
+NOTE: **Note:**
+When mocking resolved values, make sure the structure of the response is the same as actual API response: i.e. root property should be `data` for example
+
+When testing queries, please keep in mind they are promises, so they need to be _resolved_ to render a result. Without resolving, we can check the `loading` state of the query:
+
+```javascript
+it('renders a loading state', () => {
+  createComponentWithApollo();
+
+  expect(wrapper.find(LoadingSpinner).exists()).toBe(true)
+});
+
+it('renders designs list', async () => {
+  createComponentWithApollo();
+
+  jest.runOnlyPendingTimers();
+  await wrapper.vm.$nextTick();
+
+  expect(findDesigns()).toHaveLength(3);
+});
+```
+
+If we need to test a query error, we need to mock a rejected value as request handler:
+
+```javascript
+function createComponentWithApollo() {
+  ...
+  const requestHandlers = [
+    [getDesignListQuery, jest.fn().mockRejectedValue(new Error('GraphQL error')],
+  ];
+  ...
+}
+...
+
+it('renders error if query fails', async () => {
+  createComponent()
+
+  jest.runOnlyPendingTimers();
+  await wrapper.vm.$nextTick();
+
+  expect(wrapper.find('.test-error').exists()).toBe(true)
+})
+```
+
+Request handlers can also be passed to component factory as a parameter.
+
+Mutations could be tested the same way with a few additional `nextTick`s to get the updated result:
+
+```javascript
+function createComponentWithApollo({
+  moveHandler = jest.fn().mockResolvedValue(moveDesignMutationResponse),
+}) {
+  moveDesignHandler = moveHandler;
+
+  const requestHandlers = [
+    [getDesignListQuery, jest.fn().mockResolvedValue(designListQueryResponse)],
+    [permissionsQuery, jest.fn().mockResolvedValue(permissionsQueryResponse)],
+    [moveDesignMutation, moveDesignHandler],
+  ];
+
+  fakeApollo = createMockApollo(requestHandlers);
+  wrapper = shallowMount(Index, {
+    localVue,
+    apolloProvider: fakeApollo,
+  });
+}
+...
+it('calls a mutation with correct parameters and reorders designs', async () => {
+  createComponentWithApollo({});
+
+  wrapper.find(VueDraggable).vm.$emit('change', {
+    moved: {
+      newIndex: 0,
+      element: designToMove,
+    },
+  });
+
+  expect(moveDesignHandler).toHaveBeenCalled();
+
+  await wrapper.vm.$nextTick();
+
+  expect(
+    findDesigns()
+      .at(0)
+      .props('id'),
+  ).toBe('2');
+});
+```
+
 ## Handling errors
 
 GitLab's GraphQL mutations currently have two distinct error modes: [Top-level](#top-level-errors) and [errors-as-data](#errors-as-data).
diff --git a/doc/development/fe_guide/style/index.md b/doc/development/fe_guide/style/index.md
index 8d70d4db893..4ca409664de 100644
--- a/doc/development/fe_guide/style/index.md
+++ b/doc/development/fe_guide/style/index.md
@@ -1,11 +1,11 @@
 # GitLab development style guides
 
-See below the relevant style guides, guidelines, linting, and other information for developing GitLab.
+See below for the relevant style guides, guidelines, linting, and other information for developing GitLab.
 
 ## JavaScript style guide
 
 We use `eslint` to enforce our [JavaScript style guides](javascript.md). Our guide is based on
-the excellent [AirBnB](https://github.com/airbnb/javascript) style guide with a few small
+the excellent [Airbnb](https://github.com/airbnb/javascript) style guide with a few small
 changes.
 
 ## SCSS style guide
diff --git a/doc/development/fe_guide/vuex.md b/doc/development/fe_guide/vuex.md
index 9573dd36e63..4badf3f0845 100644
--- a/doc/development/fe_guide/vuex.md
+++ b/doc/development/fe_guide/vuex.md
@@ -55,10 +55,6 @@ export const createStore = () =>
   });
 ```
 
-_Note:_ Until this
-[RFC](https://gitlab.com/gitlab-org/frontend/rfcs/-/issues/20) is implemented,
-the above will need to disable the `import/prefer-default-export` ESLint rule.
-
 ### `state.js`
 
 The first thing you should do before writing any code is to design the state.
@@ -220,12 +216,15 @@ A mutation written like this is harder to maintain and more error prone. We shou
 // Good
 export default {
   [types.MARK_AS_CLOSED](state, itemId) {
-    const item = state.items.find(i => i.id == itemId);
-    Vue.set(item, 'closed', true)
+    const item = state.items.find(x => x.id === itemId);
 
-    state.items.splice(index, 1, item)
-  }
-}
+    if (!item) {
+      return;
+    }
+
+    Vue.set(item, 'closed', true);
+  },
+};
 ```
 
 This approach is better because: