Backend GraphQL API guide

# This usage is expected.
query {
  project {
    environments
  }
}

# This usage is NOT expected.
# It results in N+1 query problem. EnvironmentsResolver can't use GraphQL batch loader in favor of GraphQL pagination.
query {
  projects {
    nodes {
      environments
    }
  }
}

# This allows maximum 1 call to the `environments` field. If the field is evaluated on more than one node,
# it raises an error.
field :environments do
        extension(::Gitlab::Graphql::Limit::FieldCallCount, limit: 1)
      end

module Resolvers
  class EnvironmentsResolver < BaseResolver
    extension(::Gitlab::Graphql::Limit::FieldCallCount, limit: 1)
    # ...
  end
end

field :environments,
      description: 'Environments of the project. This field can only be resolved for one project in any single request.'

graphql_name 'Project'

field :full_path, GraphQL::Types::ID, null: true
field :name, GraphQL::Types::String, null: true

class Types::MergeRequestType < BaseObject
  present_using MergeRequestPresenter

  name 'MergeRequest'
end

  id: ProjectID!

  errors: [String!]!

field :reply_id, Types::GlobalIDType[Discussion]

def reply_id
  Gitlab::GlobalId.build(object, id: object.reply_id)
end

markdown_field :note_html, null: false

# This allows maximum 1 call to the `environments` field. If the field is evaluated on more than one node,
# it raises an error.
field :environments do
        extension(::Gitlab::Graphql::Limit::FieldCallCount, limit: 1)
      end
```0

The field is given this description by default:

> The GitLab Flavored Markdown rendering of `note`

This can be overridden by passing a `description:` argument.

### Connection types

NOTE:
For specifics on implementation, see [Pagination implementation](#pagination-implementation).

GraphQL uses [cursor based pagination](https://graphql.org/learn/pagination/#pagination-and-edges)
to expose collections of items. This provides the clients with a lot
of flexibility while also allowing the backend to use different
pagination models.

To expose a collection of resources we can use a connection type. This wraps the array with default pagination fields. For example a query for project-pipelines could look like this:

```ruby
# This allows maximum 1 call to the `environments` field. If the field is evaluated on more than one node,
# it raises an error.
field :environments do
        extension(::Gitlab::Graphql::Limit::FieldCallCount, limit: 1)
      end
```1

This would return the first 2 pipelines of a project and related
pagination information, ordered by descending ID. The returned data would
look like this:

```ruby
# This allows maximum 1 call to the `environments` field. If the field is evaluated on more than one node,
# it raises an error.
field :environments do
        extension(::Gitlab::Graphql::Limit::FieldCallCount, limit: 1)
      end
```2

To get the next page, the cursor of the last known element could be
passed:

```ruby
# This allows maximum 1 call to the `environments` field. If the field is evaluated on more than one node,
# it raises an error.
field :environments do
        extension(::Gitlab::Graphql::Limit::FieldCallCount, limit: 1)
      end
```3

To ensure that we get consistent ordering, we append an ordering on the primary
key, in descending order. The primary key is usually `id`, so we add `order(id: :desc)`
to the end of the relation. A primary key _must_ be available on the underlying table.

#### Shortcut fields

Sometimes it can seem straightforward to implement a "shortcut field", having the resolver return the first of a collection if no parameters are passed.
These "shortcut fields" are discouraged because they create maintenance overhead.
They need to be kept in sync with their canonical field, and deprecated or modified if their canonical field changes.
Use the functionality the framework provides unless there is a compelling reason to do otherwise.

For example, instead of `latest_pipeline`, use `pipelines(last: 1)`.

#### Page size limit

By default, the API returns at most a maximum number of records defined in
[`app/graphql/gitlab_schema.rb`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/graphql/gitlab_schema.rb)
per page in a connection and this is also the default number of records
returned per page if no limiting arguments (`first:` or `last:`) are provided by a client.

The `max_page_size` argument can be used to specify a different page size limit
for a connection.

WARNING:
It's better to change the frontend client, or product requirements, to not need large amounts of
records per page than it is to raise the `max_page_size`, as the default is set to ensure
the GraphQL API remains performant.

For example:

```ruby
# This allows maximum 1 call to the `environments` field. If the field is evaluated on more than one node,
# it raises an error.
field :environments do
        extension(::Gitlab::Graphql::Limit::FieldCallCount, limit: 1)
      end
```4

### Field complexity

The GitLab GraphQL API uses a _complexity_ score to limit performing overly complex queries.
Complexity is described in [our client documentation](../api/graphql/index.md#maximum-query-complexity) on the topic.

Complexity limits are defined in [`app/graphql/gitlab_schema.rb`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/graphql/gitlab_schema.rb).

By default, fields add `1` to a query's complexity score. This can be overridden by
[providing a custom `complexity`](https://graphql-ruby.org/queries/complexity_and_depth.html) value for a field.

Developers should specify higher complexity for fields that cause more _work_ to be performed
by the server to return data. Fields that represent data that can be returned
with little-to-no _work_, for example in most cases; `id` or `title`, can be given a complexity of `0`.

### `calls_gitaly`

Fields that have the potential to perform a [Gitaly](../administration/gitaly/index.md) call when resolving _must_ be marked as
such by passing `calls_gitaly: true` to `field` when defining it.

For example:

```ruby
# This allows maximum 1 call to the `environments` field. If the field is evaluated on more than one node,
# it raises an error.
field :environments do
        extension(::Gitlab::Graphql::Limit::FieldCallCount, limit: 1)
      end
```5

This increments the [`complexity` score](#field-complexity) of the field by `1`.

If a resolver calls Gitaly, it can be annotated with
`BaseResolver.calls_gitaly!`. This passes `calls_gitaly: true` to any
field that uses this resolver.

For example:

```ruby
# This allows maximum 1 call to the `environments` field. If the field is evaluated on more than one node,
# it raises an error.
field :environments do
        extension(::Gitlab::Graphql::Limit::FieldCallCount, limit: 1)
      end
```6

Then when we use it, any field that uses `BranchResolver` has the correct
value for `calls_gitaly:`.

### Exposing permissions for a type

To expose permissions the current user has on a resource, you can call
the `expose_permissions` passing in a separate type representing the
permissions for the resource.

For example:

```ruby
# This allows maximum 1 call to the `environments` field. If the field is evaluated on more than one node,
# it raises an error.
field :environments do
        extension(::Gitlab::Graphql::Limit::FieldCallCount, limit: 1)
      end
```7

The permission type inherits from `BasePermissionType` which includes
some helper methods, that allow exposing permissions as non-nullable
booleans:

```ruby
# This allows maximum 1 call to the `environments` field. If the field is evaluated on more than one node,
# it raises an error.
field :environments do
        extension(::Gitlab::Graphql::Limit::FieldCallCount, limit: 1)
      end
```8

- **`permission_field`**: Acts the same as `graphql-ruby`'s
  `field` method but setting a default description and type and making
  them non-nullable. These options can still be overridden by adding
  them as arguments.
- **`ability_field`**: Expose an ability defined in our policies. This
  behaves the same way as `permission_field` and the same
  arguments can be overridden.
- **`abilities`**: Allows exposing several abilities defined in our
  policies at once. The fields for these must all be non-nullable
  booleans with a default description.

## Feature flags

You can implement [feature flags](../development/feature_flags/index.md) in GraphQL to toggle:

- The return value of a field.
- The behavior of an argument or mutation.

This can be done in a resolver, in the
type, or even in a model method, depending on your preference and
situation.

NOTE:
It's recommended that you also [mark the item as an experiment](#mark-schema-items-as-experiments) while it is behind a feature flag.
This signals to consumers of the public GraphQL API that the field is not
meant to be used yet.
You can also
[change or remove experimental items at any time](#breaking-change-exemptions) without needing to deprecate them. When the flag is removed, "release"
the schema item by removing its `experiment` property to make it public.

### Descriptions for feature-flagged items

When using a feature flag to toggle the value or behavior of a schema item, the
`description` of the item must:

- State that the value or behavior can be toggled by a feature flag.
- Name the feature flag.
- State what the field returns, or behavior is, when the feature flag is disabled (or
  enabled, if more appropriate).

### Examples of using feature flags

#### Feature-flagged field

A field value is toggled based on the feature flag state. A common use is to return `null` if the feature flag is disabled:

```ruby
# This allows maximum 1 call to the `environments` field. If the field is evaluated on more than one node,
# it raises an error.
field :environments do
        extension(::Gitlab::Graphql::Limit::FieldCallCount, limit: 1)
      end
```9

#### Feature-flagged argument

An argument can be ignored, or have its value changed, based on the feature flag state.
A common use is to ignore the argument when a feature flag is disabled:

```ruby
module Resolvers
  class EnvironmentsResolver < BaseResolver
    extension(::Gitlab::Graphql::Limit::FieldCallCount, limit: 1)
    # ...
  end
end
```0

#### Feature-flagged mutation

A mutation that cannot be performed due to a feature flag state is handled as a
[non-recoverable mutation error](#failure-irrelevant-to-the-user). The error is returned at the top level:

```ruby
module Resolvers
  class EnvironmentsResolver < BaseResolver
    extension(::Gitlab::Graphql::Limit::FieldCallCount, limit: 1)
    # ...
  end
end
```1

## Deprecating schema items

The GitLab GraphQL API is versionless, which means we maintain backwards
compatibility with older versions of the API with every change.

Rather than removing fields, arguments, [enum values](#enums), or [mutations](#mutations),
they must be _deprecated_ instead.

The deprecated parts of the schema can then be removed in a future release
in accordance with the [GitLab deprecation process](../api/graphql/index.md#deprecation-and-removal-process).

To deprecate a schema item in GraphQL:

1. [Create a deprecation issue](#create-a-deprecation-issue) for the item.
1. [Mark the item as deprecated](#mark-the-item-as-deprecated) in the schema.

See also:

- [Aliasing and deprecating mutations](#aliasing-and-deprecating-mutations).
- [Marking schema items as experiments](#mark-schema-items-as-experiments).
- [How to filter Kibana for queries that used deprecated fields](graphql_guide/monitoring.md#queries-that-used-a-deprecated-field).

### Create a deprecation issue

Every GraphQL deprecation should have a deprecation issue created [using the `Deprecations` issue template](https://gitlab.com/gitlab-org/gitlab/-/issues/new?issuable_template=Deprecations) to track its deprecation and removal.

Apply these two labels to the deprecation issue:

- `~GraphQL`
- `~deprecation`

### Mark the item as deprecated

Fields, arguments, enum values, and mutations are deprecated using the `deprecated` property. The value of the property is a `Hash` of:

- `reason` - Reason for the deprecation.
- `milestone` - Milestone that the field was deprecated.

Example:

```ruby
module Resolvers
  class EnvironmentsResolver < BaseResolver
    extension(::Gitlab::Graphql::Limit::FieldCallCount, limit: 1)
    # ...
  end
end
```2

The original `description` of the things being deprecated should be maintained,
and should _not_ be updated to mention the deprecation. Instead, the `reason`
is appended to the `description`.

#### Deprecation reason style guide

Where the reason for deprecation is due to the field, argument, or enum value being
replaced, the `reason` must indicate the replacement. For example, the
following is a `reason` for a replaced field:

```ruby
module Resolvers
  class EnvironmentsResolver < BaseResolver
    extension(::Gitlab::Graphql::Limit::FieldCallCount, limit: 1)
    # ...
  end
end
```3

Examples:

```ruby
module Resolvers
  class EnvironmentsResolver < BaseResolver
    extension(::Gitlab::Graphql::Limit::FieldCallCount, limit: 1)
    # ...
  end
end
```4

```ruby
module Resolvers
  class EnvironmentsResolver < BaseResolver
    extension(::Gitlab::Graphql::Limit::FieldCallCount, limit: 1)
    # ...
  end
end
```5

If the field, argument, or enum value being deprecated is not being replaced,
a descriptive deprecation `reason` should be given.

#### Deprecate Global IDs

We use the [`rails/globalid`](https://github.com/rails/globalid) gem to generate and parse
Global IDs, so as such they are coupled to model names. When we rename a
model, its Global ID changes.

If the Global ID is used as an _argument_ type anywhere in the schema, then the Global ID
change would typically constitute a breaking change.

To continue to support clients using the old Global ID argument, we add a deprecation
to `Gitlab::GlobalId::Deprecations`.

NOTE:
If the Global ID is _only_ [exposed as a field](#exposing-global-ids) then we do not need to
deprecate it. We consider the change to the way a Global ID is expressed in a field to be
backwards-compatible. We expect that clients don't parse these values: they are meant to
be treated as opaque tokens, and any structure in them is incidental and not to be relied on.

**Example scenario:**

This example scenario is based on this [merge request](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/62645).

A model named `PrometheusService` is to be renamed `Integrations::Prometheus`. The old model
name is used to create a Global ID type that is used as an argument for a mutation:

```ruby
module Resolvers
  class EnvironmentsResolver < BaseResolver
    extension(::Gitlab::Graphql::Limit::FieldCallCount, limit: 1)
    # ...
  end
end
```6

Clients call the mutation by passing a Global ID string that looks like
`"gid://gitlab/PrometheusService/1"`, named as `PrometheusServiceID`, as the `input.id` argument:

```ruby
module Resolvers
  class EnvironmentsResolver < BaseResolver
    extension(::Gitlab::Graphql::Limit::FieldCallCount, limit: 1)
    # ...
  end
end
```7

We rename the model to `Integrations::Prometheus`, and then update the codebase with the new name.
When we come to update the mutation, we pass the renamed model to `Types::GlobalIDType[]`:

```ruby
module Resolvers
  class EnvironmentsResolver < BaseResolver
    extension(::Gitlab::Graphql::Limit::FieldCallCount, limit: 1)
    # ...
  end
end
```8

This would cause a breaking change to the mutation, as the API now rejects clients who
pass an `id` argument as `"gid://gitlab/PrometheusService/1"`, or that specify the argument
type as `PrometheusServiceID` in the query signature.

To allow clients to continue to interact with the mutation unchanged, edit the `DEPRECATIONS` constant in
`Gitlab::GlobalId::Deprecations` and add a new `Deprecation` to the array:

```ruby
module Resolvers
  class EnvironmentsResolver < BaseResolver
    extension(::Gitlab::Graphql::Limit::FieldCallCount, limit: 1)
    # ...
  end
end
```9

Then follow our regular [deprecation process](../api/graphql/index.md#deprecation-and-removal-process). To later remove
support for the former argument style, remove the `Deprecation`:

```ruby
field :environments,
      description: 'Environments of the project. This field can only be resolved for one project in any single request.'
```0

During the deprecation period, the API accepts either of these formats for the argument value:

- `"gid://gitlab/PrometheusService/1"`
- `"gid://gitlab/Integrations::Prometheus/1"`

The API also accepts these types in the query signature for the argument:

- `PrometheusServiceID`
- `IntegrationsPrometheusID`

NOTE:
Although queries that use the old type (`PrometheusServiceID` in this example) are
considered valid and executable by the API, validator tools consider them to be invalid.
They are considered invalid because we are deprecating using a bespoke method outside of the
[`@deprecated` directive](https://spec.graphql.org/June2018/#sec--deprecated), so validators are not
aware of the support.

The documentation mentions that the old Global ID style is now deprecated.

## Mark schema items as experiments

You can mark GraphQL schema items (fields, arguments, enum values, and mutations) as
[experiments](../policy/development_stages_support.md#experiment).

An item marked as an experiment is
[exempt from the deprecation process](../api/graphql/index.md#breaking-change-exemptions) and can be
removed at any time without notice. Mark an item as an experiment when it is subject to
change and not ready for public use.

NOTE:
Only mark new items as an experiment. Never mark existing items
as an experiment because they're already public.

To mark a schema item as an experiment, use the `experiment:` keyword.
You must provide the `milestone:` that introduced the experimental item.

For example:

```ruby
field :environments,
      description: 'Environments of the project. This field can only be resolved for one project in any single request.'
```1

Similarly, you can also mark an entire mutation as an experiment by updating where the mutation is mounted in `app/graphql/types/mutation_type.rb`:

```ruby
field :environments,
      description: 'Environments of the project. This field can only be resolved for one project in any single request.'
```2

Experimental GraphQL items is a custom GitLab feature that leverages GraphQL deprecations. An experimental item
appears as deprecated in the GraphQL schema. Like all deprecated schema items, you can test an
experimental field in the [interactive GraphQL explorer](../api/graphql/index.md#interactive-graphql-explorer) (GraphiQL).
However, be aware that the GraphiQL autocomplete editor doesn't suggest deprecated fields.

The item shows as `experiment` in our generated GraphQL documentation and its GraphQL schema description.

## Enums

GitLab GraphQL enums are defined in `app/graphql/types`. When defining new enums, the
following rules apply:

- Values must be uppercase.
- Class names must end with the string `Enum`.
- The `graphql_name` must not contain the string `Enum`.

For example:

```ruby
field :environments,
      description: 'Environments of the project. This field can only be resolved for one project in any single request.'
```3

If the enum is used for a class property in Ruby that is not an uppercase string,
you can provide a `value:` option that adapts the uppercase value.

In the following example:

- GraphQL inputs of `OPENED` are converted to `'opened'`.
- Ruby values of `'opened'` are converted to `"OPENED"` in GraphQL responses.

```ruby
field :environments,
      description: 'Environments of the project. This field can only be resolved for one project in any single request.'
```4

Enum values can be deprecated using the
[`deprecated` keyword](#deprecating-schema-items).

### Defining GraphQL enums dynamically from Rails enums

If your GraphQL enum is backed by a [Rails enum](database/creating_enums.md), then consider
using the Rails enum to dynamically define the GraphQL enum values. Doing so
binds the GraphQL enum values to the Rails enum definition, so if values are
ever added to the Rails enum then the GraphQL enum automatically reflects the change.

Example:

```ruby
field :environments,
      description: 'Environments of the project. This field can only be resolved for one project in any single request.'
```5

## JSON

When data to be returned by GraphQL is stored as
[JSON](migration_style_guide.md#storing-json-in-database), we should continue to use
GraphQL types whenever possible. Avoid using the `GraphQL::Types::JSON` type unless
the JSON data returned is _truly_ unstructured.

If the structure of the JSON data varies, but is one of a set of known possible
structures, use a
[union](https://graphql-ruby.org/type_definitions/unions.html).
An example of the use of a union for this purpose is
[!30129](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/30129).

Field names can be mapped to hash data keys using the `hash_key:` keyword if needed.

For example, given the following JSON data:

```ruby
field :environments,
      description: 'Environments of the project. This field can only be resolved for one project in any single request.'
```6

We can use GraphQL types like this:

```ruby
field :environments,
      description: 'Environments of the project. This field can only be resolved for one project in any single request.'
```7

## Descriptions

All fields and arguments
[must have descriptions](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/16438).

A description of a field or argument is given using the `description:`
keyword. For example:

```ruby
field :environments,
      description: 'Environments of the project. This field can only be resolved for one project in any single request.'
```8

You can view descriptions of fields and arguments in:

- The [GraphiQL explorer](#graphiql).
- The [static GraphQL API reference](../api/graphql/reference/index.md).

### Description style guide

#### Language and punctuation

To describe fields and arguments, use `{x} of the {y}` where possible,
where `{x}` is the item you're describing, and `{y}` is the resource it applies to. For example:

```ruby
field :environments,
      description: 'Environments of the project. This field can only be resolved for one project in any single request.'
```9

```ruby
graphql_name 'Project'

field :full_path, GraphQL::Types::ID, null: true
field :name, GraphQL::Types::String, null: true
```0

For arguments that sort or search, start with the appropriate verb.
To indicate the specified values, for conciseness, you can use `this` instead of
`the given` or `the specified`. For example:

```ruby
graphql_name 'Project'

field :full_path, GraphQL::Types::ID, null: true
field :name, GraphQL::Types::String, null: true
```1

Do not start descriptions with `The` or `A`, for consistency and conciseness.

End all descriptions with a period (`.`).

#### Booleans

For a boolean field (`GraphQL::Types::Boolean`), start with a verb that describes
what it does. For example:

```ruby
graphql_name 'Project'

field :full_path, GraphQL::Types::ID, null: true
field :name, GraphQL::Types::String, null: true
```2

If necessary, provide the default. For example:

```ruby
graphql_name 'Project'

field :full_path, GraphQL::Types::ID, null: true
field :name, GraphQL::Types::String, null: true
```3

#### Sort enums

[Enums for sorting](#sort-arguments) should have the description `'Values for sorting {x}.'`. For example:

```ruby
graphql_name 'Project'

field :full_path, GraphQL::Types::ID, null: true
field :name, GraphQL::Types::String, null: true
```4

#### `Types::TimeType` field description

For `Types::TimeType` GraphQL fields, include the word `timestamp`. This lets
the reader know that the format of the property is `Time`, rather than just `Date`.

For example:

```ruby
graphql_name 'Project'

field :full_path, GraphQL::Types::ID, null: true
field :name, GraphQL::Types::String, null: true
```5

### `copy_field_description` helper

Sometimes we want to ensure that two descriptions are always identical.
For example, to keep a type field description the same as a mutation argument
when they both represent the same property.

Instead of supplying a description, we can use the `copy_field_description` helper,
passing it the type, and field name to copy the description of.

Example:

```ruby
graphql_name 'Project'

field :full_path, GraphQL::Types::ID, null: true
field :name, GraphQL::Types::String, null: true
```6

### Documentation references

Sometimes we want to refer to external URLs in our descriptions. To make this
easier, and provide proper markup in the generated reference documentation, we
provide a `see` property on fields. For example:

```ruby
graphql_name 'Project'

field :full_path, GraphQL::Types::ID, null: true
field :name, GraphQL::Types::String, null: true
```7

This renders in our documentation as:

```ruby
graphql_name 'Project'

field :full_path, GraphQL::Types::ID, null: true
field :name, GraphQL::Types::String, null: true
```8

Multiple documentation references can be provided. The syntax for this property
is a `HashMap` where the keys are textual descriptions, and the values are URLs.

### Subscription tier badges

If a field or argument is available to higher subscription tiers than the other fields,
add the [availability details inline](documentation/styleguide/availability_details.md#inline-availability-details).

For example:

```ruby
graphql_name 'Project'

field :full_path, GraphQL::Types::ID, null: true
field :name, GraphQL::Types::String, null: true
```9

## Authorization

See: [GraphQL Authorization](graphql_guide/authorization.md)

## Resolvers

We define how the application serves the response using _resolvers_
stored in the `app/graphql/resolvers` directory.
The resolver provides the actual implementation logic for retrieving
the objects in question.

To find objects to display in a field, we can add resolvers to
`app/graphql/resolvers`.

Arguments can be defined in the resolver in the same way as in a mutation.
See the [Arguments](#arguments) section.

To limit the amount of queries performed, we can use [BatchLoader](graphql_guide/batchloader.md).

### Writing resolvers

Our code should aim to be thin declarative wrappers around finders and [services](../development/reusing_abstractions.md#service-classes). You can
repeat lists of arguments, or extract them to concerns. Composition is preferred over
inheritance in most cases. Treat resolvers like controllers: resolvers should be a DSL
that compose other application abstractions.

For example:

```ruby
class Types::MergeRequestType < BaseObject
  present_using MergeRequestPresenter

  name 'MergeRequest'
end
```0

While you can use the same resolver class in two different places,
such as in two different fields where the same object is exposed,
you should never re-use resolver objects directly. Resolvers have a complex lifecycle, with
authorization, readiness and resolution orchestrated by the framework, and at
each stage [lazy values](#laziness) can be returned to take advantage of batching
opportunities. Never instantiate a resolver or a mutation in application code.

Instead, the units of code reuse are much the same as in the rest of the
application:

- Finders in queries to look up data.
- Services in mutations to apply operations.
- Loaders (batch-aware finders) specific to queries.

There is never any reason to use batching in a mutation. Mutations are
executed in series, so there are no batching opportunities. All values are
evaluated eagerly as soon as they are requested, so batching is unnecessary
overhead. If you are writing:

- A `Mutation`, feel free to lookup objects directly.
- A `Resolver` or methods on a `BaseObject`, then you want to allow for batching.

### Error handling

Resolvers may raise errors, which are converted to top-level errors as
appropriate. All anticipated errors should be caught and transformed to an
appropriate GraphQL error (see
[`Gitlab::Graphql::Errors`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/graphql/errors.rb)).
Any uncaught errors are suppressed and the client receives the message
`Internal service error`.

The one special case is permission errors. In the REST API we return
`404 Not Found` for any resources that the user does not have permission to
access. The equivalent behavior in GraphQL is for us to return `null` for
all absent or unauthorized resources.
Query resolvers **should not raise errors for unauthorized resources**.

The rationale for this is that clients must not be able to distinguish between
the absence of a record and the presence of one they do not have access to. To
do so is a security vulnerability, because it leaks information we want to keep
hidden.

In most cases you don't need to worry about this - this is handled correctly by
the resolver field authorization we declare with the `authorize` DSL calls. If
you need to do something more custom however, remember, if you encounter an
object the `current_user` does not have access to when resolving a field, then
the entire field should resolve to `null`.

### Deriving resolvers

(including `BaseResolver.single` and `BaseResolver.last`)

For some use cases, we can derive resolvers from others.
The main use case for this is one resolver to find all items, and another to
find one specific one. For this, we supply convenience methods:

- `BaseResolver.single`, which constructs a new resolver that selects the first item.
- `BaseResolver.last`, which constructs a resolver that selects the last item.

The correct singular type is inferred from the collection type, so we don't have
to define the `type` here.

Before you make use of these methods, consider if it would be simpler to either:

- Write another resolver that defines its own arguments.
- Write a concern that abstracts out the query.

Using `BaseResolver.single` too freely is an anti-pattern. It can lead to
non-sensical fields, such as a `Project.mergeRequest` field that just returns
the first MR if no arguments are given. Whenever we derive a single resolver
from a collection resolver, it must have more restrictive arguments.

To make this possible, use the `when_single` block to customize the single
resolver. Every `when_single` block must:

- Define (or re-define) at least one argument.
- Make optional filters required.

For example, we can do this by redefining an existing optional argument,
changing its type and making it required:

```ruby
class Types::MergeRequestType < BaseObject
  present_using MergeRequestPresenter

  name 'MergeRequest'
end
```1

Here we have a resolver for getting pipeline jobs. The `name` argument is
optional when getting a list, but required when getting a single job.

If there are multiple arguments, and neither can be made required, we can use
the block to add a ready condition:

```ruby
class Types::MergeRequestType < BaseObject
  present_using MergeRequestPresenter

  name 'MergeRequest'
end
```2

Then we can use these resolver on fields:

```ruby
class Types::MergeRequestType < BaseObject
  present_using MergeRequestPresenter

  name 'MergeRequest'
end
```3

### Optimizing Resolvers

#### Look-Ahead

The full query is known in advance during execution, which means we can make use
of [lookahead](https://graphql-ruby.org/queries/lookahead.html) to optimize our
queries, and batch load associations we know we need. Consider adding
lookahead support in your resolvers to avoid `N+1` performance issues.

To enable support for common lookahead use-cases (pre-loading associations when
child fields are requested), you can
include [`LooksAhead`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/graphql/resolvers/concerns/looks_ahead.rb). For example:

```ruby
class Types::MergeRequestType < BaseObject
  present_using MergeRequestPresenter

  name 'MergeRequest'
end
```4

By default, fields defined in `#preloads` are preloaded if that field
is selected in the query. Occasionally, finer control may be
needed to avoid preloading too much or incorrect content.

Extending the above example, we might want to preload a different
association if certain fields are requested together. This can
be done by overriding `#filtered_preloads`:

```ruby
class Types::MergeRequestType < BaseObject
  present_using MergeRequestPresenter

  name 'MergeRequest'
end
```5

The `LooksAhead` concern also provides basic support for preloading associations based on nested GraphQL field
definitions. The [WorkItemsResolver](https://gitlab.com/gitlab-org/gitlab/-/blob/e824a7e39e08a83fb162db6851de147cf0bfe14a/app/graphql/resolvers/work_items_resolver.rb#L46)
is a good example for this. `nested_preloads` is another method you can define to return a hash, but unlike the
`preloads` method, the value for each hash key is another hash and not the list of associations to preload. So in
the previous example, you could override `nested_preloads` like this:

```ruby
class Types::MergeRequestType < BaseObject
  present_using MergeRequestPresenter

  name 'MergeRequest'
end
```6

For an example of real world use,
see [`ResolvesMergeRequests`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/graphql/resolvers/concerns/resolves_merge_requests.rb).

#### `before_connection_authorization`

A `before_connection_authorization` hook can help resolvers eliminate N+1 problems that originate from
[type authorization](graphql_guide/authorization.md#type-authorization) permission checks.

The `before_connection_authorization` method receives the resolved nodes and the current user. In
the block, use `ActiveRecord::Associations::Preloader` or a `Preloaders::` class to preload data
for the type authorization check.

Example:

```ruby
class Types::MergeRequestType < BaseObject
  present_using MergeRequestPresenter

  name 'MergeRequest'
end
```7

#### BatchLoading

See [GraphQL BatchLoader](graphql_guide/batchloader.md).

### Correct use of `Resolver#ready?`

Resolvers have two public API methods as part of the framework: `#ready?(**args)` and `#resolve(**args)`.
We can use `#ready?` to perform set-up or early-return without invoking `#resolve`.

Good reasons to use `#ready?` include:

- Returning `Relation.none` if we know before-hand that no results are possible.
- Performing setup such as initializing instance variables (although consider lazily initialized methods for this).

Implementations of [`Resolver#ready?(**args)`](https://graphql-ruby.org/api-doc/1.10.9/GraphQL/Schema/Resolver#ready%3F-instance_method) should
return `(Boolean, early_return_data)` as follows:

```ruby
class Types::MergeRequestType < BaseObject
  present_using MergeRequestPresenter

  name 'MergeRequest'
end
```8

For this reason, whenever you call a resolver (mainly in tests because framework
abstractions Resolvers should not be considered re-usable, finders are to be
preferred), remember to call the `ready?` method and check the boolean flag
before calling `resolve`! An example can be seen in our [`GraphqlHelpers`](https://gitlab.com/gitlab-org/gitlab/-/blob/2d395f32d2efbb713f7bc861f96147a2a67e92f2/spec/support/helpers/graphql_helpers.rb#L20-27).

For validating arguments, [validators](https://graphql-ruby.org/fields/validation.html) are preferred over using `#ready?`.

### Negated arguments

Negated filters can filter some resources (for example, find all issues that
have the `bug` label, but don't have the `bug2` label assigned). The `not`
argument is the preferred syntax to pass negated arguments:

```ruby
class Types::MergeRequestType < BaseObject
  present_using MergeRequestPresenter

  name 'MergeRequest'
end
```9

You can use the `negated` helper from `Gitlab::Graphql::NegatableArguments` in your type or resolver.
For example:

```graphql
  id: ProjectID!
```0

### Metadata

When using resolvers, they can and should serve as the SSoT for field metadata.
All field options (apart from the field name) can be declared on the resolver.
These include:

- `type` (required - all resolvers must include a type annotation)
- `extras`
- `description`
- Gitaly annotations (with `calls_gitaly!`)

Example:

```graphql
  id: ProjectID!
```1

### Pass a parent object into a child Presenter

Sometimes you need to access the resolved query parent in a child context to compute fields. Usually the parent is only
available in the `Resolver` class as `parent`.

To find the parent object in your `Presenter` class:

1. Add the parent object to the GraphQL `context` from your resolver's `resolve` method:

   ```ruby
     def resolve(**args)
       context[:parent_object] = parent
     end

  id: ProjectID!
```2

Due to changes in the `1.13` version of the `graphql-ruby` gem, `graphql_name` should be the first
line of the class to ensure that type names are generated correctly. The `Graphql::GraphqlNamePosition` cop enforces this.
See [issue #27536](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/27536#note_840245581) for further context.

Our GraphQL mutation names are historically inconsistent, but new mutation names should follow the
convention `'{Resource}{Action}'` or `'{Resource}{Action}{Attribute}'`.

Mutations that **create** new resources should use the verb `Create`.

Example:

- `CommitCreate`

Mutations that **update** data should use:

- The verb `Update`.
- A domain-specific verb like `Set`, `Add`, or `Toggle` if more appropriate.

Examples:

- `EpicTreeReorder`
- `IssueSetWeight`
- `IssueUpdate`
- `TodoMarkDone`

Mutations that **remove** data should use:

- The verb `Delete` rather than `Destroy`.
- A domain-specific verb like `Remove` if more appropriate.

Examples:

- `AwardEmojiRemove`
- `NoteDelete`

If you need advice for mutation naming, canvass the Slack `#graphql` channel for feedback.

### Fields

In the most common situations, a mutation would return 2 fields:

- The resource being modified
- A list of errors explaining why the action could not be
  performed. If the mutation succeeded, this list would be empty.

By inheriting any new mutations from `Mutations::BaseMutation` the
`errors` field is automatically added. A `clientMutationId` field is
also added, this can be used by the client to identify the result of a
single mutation when multiple are performed in a single request.

### The `resolve` method

Similar to [writing resolvers](#writing-resolvers), the `resolve` method of a mutation
should aim to be a thin declarative wrapper around a
[service](../development/reusing_abstractions.md#service-classes).

The `resolve` method receives the mutation's arguments as keyword arguments.
From here, we can call the service that modifies the resource.

The `resolve` method should then return a hash with the same field
names as defined on the mutation including an `errors` array. For example,
the `Mutations::MergeRequests::SetDraft` defines a `merge_request`
field:

```graphql
  id: ProjectID!
```3

This means that the hash returned from `resolve` in this mutation
should look like this:

```graphql
  id: ProjectID!
```4

### Mounting the mutation

To make the mutation available it must be defined on the mutation
type that is stored in `graphql/types/mutation_type`. The
`mount_mutation` helper method defines a field based on the
GraphQL-name of the mutation:

```graphql
  id: ProjectID!
```5

Generates a field called `mergeRequestSetDraft` that
`Mutations::MergeRequests::SetDraft` to be resolved.

### Authorizing resources

To authorize resources inside a mutation, we first provide the required
 abilities on the mutation like this:

```graphql
  id: ProjectID!
```6

We can then call `authorize!` in the `resolve` method, passing in the resource we
want to validate the abilities for.

Alternatively, we can add a `find_object` method that loads the
object on the mutation. This would allow you to use the
`authorized_find!` helper method.

When a user is not allowed to perform the action, or an object is not
found, we should raise a
`Gitlab::Graphql::Errors::ResourceNotAvailable` by calling `raise_resource_not_available_error!`
from in the `resolve` method.

### Errors in mutations

We encourage following the practice of
[errors as data](https://graphql-ruby.org/mutations/mutation_errors) for mutations, which
distinguishes errors by who they are relevant to, defined by who can deal with
them.

Key points:

- All mutation responses have an `errors` field. This should be populated on
  failure, and may be populated on success.
- Consider who needs to see the error: the **user** or the **developer**.
- Clients should always request the `errors` field when performing mutations.
- Errors may be reported to users either at `$root.errors` (top-level error) or at
  `$root.data.mutationName.errors` (mutation errors). The location depends on what kind of error
  this is, and what information it holds.
- Mutation fields [must have `null: true`](https://graphql-ruby.org/mutations/mutation_errors#nullable-mutation-payload-fields)

Consider an example mutation `doTheThing` that returns a response with
two fields: `errors: [String]`, and `thing: ThingType`. The specific nature of
the `thing` itself is irrelevant to these examples, as we are considering the
errors.

The three states a mutation response can be in are:

- [Success](#success)
- [Failure (relevant to the user)](#failure-relevant-to-the-user)
- [Failure (irrelevant to the user)](#failure-irrelevant-to-the-user)

#### Success

In the happy path, errors *may* be returned, along with the anticipated payload, but
if everything was successful, then `errors` should be an empty array, because
there are no problems we need to inform the user of.

```graphql
  id: ProjectID!
```7

#### Failure (relevant to the user)

An error that affects the **user** occurred. We refer to these as _mutation errors_.

In a _create_ mutation there is typically no `thing` to return.

In an _update_ mutation we return the current true state of `thing`. Developers may need to call `#reset` on the `thing` instance to ensure this happens.

```graphql
  id: ProjectID!
```8

Examples of this include:

- Model validation errors: the user may need to change the inputs.
- Permission errors: the user needs to know they cannot do this, they may need to request permission or sign in.
- Problems with the application state that prevent the user's action (for example, merge conflicts or a locked resource).

Ideally, we should prevent the user from getting this far, but if they do, they
need to be told what is wrong, so they understand the reason for the failure and
what they can do to achieve their intent. For example, they might only need to retry the
request.

It is possible to return *recoverable* errors alongside mutation data. For example, if
a user uploads 10 files and 3 of them fail and the rest succeed, the errors for the
failures can be made available to the user, alongside the information about
the successes.

#### Failure (irrelevant to the user)

One or more *non-recoverable* errors can be returned at the _top level_. These
are things over which the **user** has little to no control, and should mainly
be system or programming problems, that a **developer** needs to know about.
In this case there is no `data`:

```graphql
  id: ProjectID!
```9

This results from raising an error during the mutation. In our implementation,
the messages of argument errors and validation errors are returned to the client, and all other
`StandardError` instances are caught, logged and presented to the client with the message set to `"Internal server error"`.
See [`GraphqlController`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/controllers/graphql_controller.rb) for details.

These represent programming errors, such as:

- A GraphQL syntax error, where an `Int` was passed instead of a `String`, or a required argument was not present.
- Errors in our schema, such as being unable to provide a value for a non-nullable field.
- System errors: for example, a Git storage exception, or database unavailability.

The user should not be able to cause such errors in regular usage. This category
of errors should be treated as internal, and not shown to the user in specific
detail.

We need to inform the user when the mutation fails, but we do not need to
tell them why, because they cannot have caused it, and nothing they can do
fixes it, although we may offer to retry the mutation.

#### Categorizing errors

When we write mutations, we need to be conscious about which of
these two categories an error state falls into (and communicate about this with
frontend developers to verify our assumptions). This means distinguishing the
needs of the _user_ from the needs of the _client_.

> _Never catch an error unless the user needs to know about it._

If the user does need to know about it, communicate with frontend developers
to make sure the error information we are passing back is relevant and serves a purpose.

See also the [frontend GraphQL guide](../development/fe_guide/graphql.md#handling-errors).

### Aliasing and deprecating mutations

The `#mount_aliased_mutation` helper allows us to alias a mutation as
another name in `MutationType`.

For example, to alias a mutation called `FooMutation` as `BarMutation`:

```graphql

  errors: [String!]!
```0

This allows us to rename a mutation and continue to support the old name,
when coupled with the [`deprecated`](#deprecating-schema-items)
argument.

Example:

```graphql

  errors: [String!]!
```1

Deprecated mutations should be added to `Types::DeprecatedMutations` and
tested for in the unit test of `Types::MutationType`. The merge request
[!34798](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/34798)
can be referred to as an example of this, including the method of testing
deprecated aliased mutations.

#### Deprecating EE mutations

EE mutations should follow the same process. For an example of the merge request
process, read [merge request !42588](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/42588).

## Subscriptions

We use subscriptions to push updates to clients. We use the [Action Cable implementation](https://graphql-ruby.org/subscriptions/action_cable_implementation)
to deliver the messages over websockets.

When a client subscribes to a subscription, we store their query in-memory in Puma workers. Then when the subscription is triggered,
the Puma workers execute the stored GraphQL queries and push the results to the clients.

NOTE:
We cannot test subscriptions using GraphiQL, because they require an Action Cable client, which GraphiQL does not support at the moment.

### Building subscriptions

All fields under `Types::SubscriptionType` are subscriptions that clients can subscribe to. These fields require a subscription class,
which is a descendant of `Subscriptions::BaseSubscription` and is stored under `app/graphql/subscriptions`.

The arguments required to subscribe and the fields that are returned are defined in the subscription class. Multiple fields can share
the same subscription class if they have the same arguments and return the same fields.

This class runs during the initial subscription request and subsequent updates. You can read more about this in the
[GraphQL Ruby guides](https://graphql-ruby.org/subscriptions/subscription_classes).

### Authorization

You should implement the `#authorized?` method of the subscription class so that the initial subscription and subsequent updates are authorized.

When a user is not authorized, you should call the `unauthorized!` helper so that execution is halted and the user is unsubscribed. Returning `false`
results in redaction of the response, but we leak information that some updates are happening. This leakage is due to a
[bug in the GraphQL gem](https://github.com/rmosolgo/graphql-ruby/issues/3390).

### Triggering subscriptions

Define a method under the `GraphqlTriggers` module to trigger a subscription. Do not call `GitlabSchema.subscriptions.trigger` directly in application
code so that we have a single source of truth and we do not trigger a subscription with different arguments and objects.

## Pagination implementation

For more information, see [GraphQL pagination](graphql_guide/pagination.md).

## Arguments

[Arguments](https://graphql-ruby.org/fields/arguments.html) for a resolver or mutation are defined using `argument`.

Example:

```graphql

  errors: [String!]!
```2

### Nullability

Arguments can be marked as `required: true` which means the value must be present and not `null`.
If a required argument's value can be `null`, use the `required: :nullable` declaration.

Example:

```graphql

  errors: [String!]!
```3

In the above example, the `due_date` argument must be given, but unlike the GraphQL spec, the value can be `null`.
This allows 'unsetting' the due date in a single mutation rather than creating a new mutation for removing the due date.

```graphql

  errors: [String!]!
```4

#### Nullability and required: false

If an argument is marked `required: false` the client is permitted to send `null` as a value.
Often this is undesirable.

If an argument is optional but `null` is not an allowed value, use validation to ensure that passing `null` returns an error:

```graphql

  errors: [String!]!
```5

Alternatively, if you wish to allow `null` when it is not an allowed value, you can replace it with a default value:

```graphql

  errors: [String!]!
```6

See [Validation](https://graphql-ruby.org/fields/validation.html),
[Nullability](https://graphql-ruby.org/fields/arguments.html#nullability) and
[Default Values](https://graphql-ruby.org/fields/arguments.html#default-values) for more details.

### Mutually exclusive arguments

Arguments can be marked as mutually exclusive, ensuring that they are not provided at the same time.
When more than one of the listed arguments are given, a top-level error will be added.

Example:

```graphql

  errors: [String!]!
```7

When exactly one argument is required, you can use the `exactly_one_of` validator.

Example:

```graphql

  errors: [String!]!
```8

### Keywords

Each GraphQL `argument` defined is passed to the `#resolve` method
of a mutation as keyword arguments.

Example:

```graphql

  errors: [String!]!
```9

### Input Types

`graphql-ruby` wraps up arguments into an
[input type](https://graphql.org/learn/schema/#input-types).

For example, the
[`mergeRequestSetDraft` mutation](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/graphql/mutations/merge_requests/set_draft.rb)
defines these arguments (some
[through inheritance](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/graphql/mutations/merge_requests/base.rb)):

```ruby
field :reply_id, Types::GlobalIDType[Discussion]

def reply_id
  Gitlab::GlobalId.build(object, id: object.reply_id)
end
```0

These arguments automatically generate an input type called
`MergeRequestSetDraftInput` with the 3 arguments we specified and the
`clientMutationId`.

### Object identifier arguments

Arguments that identify an object should be:

- [A full path](#full-path-object-identifier-arguments) or [an IID](#iid-object-identifier-arguments) if an object has either.
- [The object's Global ID](#global-id-object-identifier-arguments) for all other objects. Never use plain database primary key IDs.

#### Full path object identifier arguments

Historically we have been inconsistent with the naming of full path arguments, but prefer to name the argument:

- `project_path` for a project full path
- `group_path` for a group full path
- `namespace_path` for a namespace full path

Using an example from the
[`ciJobTokenScopeRemoveProject` mutation](https://gitlab.com/gitlab-org/gitlab/-/blob/c40d5637f965e724c496f3cd1392cd8e493237e2/app/graphql/mutations/ci/job_token_scope/remove_project.rb#L13-15):

```ruby
field :reply_id, Types::GlobalIDType[Discussion]

def reply_id
  Gitlab::GlobalId.build(object, id: object.reply_id)
end
```1

#### IID object identifier arguments

Use the `iid` of an object in combination with its parent `project_path` or `group_path`. For example:

```ruby
field :reply_id, Types::GlobalIDType[Discussion]

def reply_id
  Gitlab::GlobalId.build(object, id: object.reply_id)
end
```2

#### Global ID object identifier arguments

Using an example from the
[`discussionToggleResolve` mutation](https://gitlab.com/gitlab-org/gitlab/-/blob/3a9d20e72225dd82fe4e1a14e3dd1ffcd0fe81fa/app/graphql/mutations/discussions/toggle_resolve.rb#L10-13):

```ruby
field :reply_id, Types::GlobalIDType[Discussion]

def reply_id
  Gitlab::GlobalId.build(object, id: object.reply_id)
end
```3

See also [Deprecate Global IDs](#deprecate-global-ids).

### Sort arguments

Sort arguments should use an [enum type](#enums) whenever possible to describe the set of available sorting values.

The enum can inherit from `Types::SortEnum` to inherit some common values.

The enum values should follow the format `{PROPERTY}_{DIRECTION}`. For example:

```ruby
field :reply_id, Types::GlobalIDType[Discussion]

def reply_id
  Gitlab::GlobalId.build(object, id: object.reply_id)
end
```4

Also see the [description style guide for sort enums](#sort-enums).

Example from [`ContainerRepositoriesResolver`](https://gitlab.com/gitlab-org/gitlab/-/blob/dad474605a06c8ed5404978b0a9bd187e9fded80/app/graphql/resolvers/container_repositories_resolver.rb#L13-16):

```ruby
field :reply_id, Types::GlobalIDType[Discussion]

def reply_id
  Gitlab::GlobalId.build(object, id: object.reply_id)
end
```5

## GitLab custom scalars

### `Types::TimeType`

[`Types::TimeType`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app%2Fgraphql%2Ftypes%2Ftime_type.rb)
must be used as the type for all fields and arguments that deal with Ruby
`Time` and `DateTime` objects.

The type is
[a custom scalar](https://github.com/rmosolgo/graphql-ruby/blob/master/guides/type_definitions/scalars.md#custom-scalars)
that:

- Converts Ruby's `Time` and `DateTime` objects into standardized
  ISO-8601 formatted strings, when used as the type for our GraphQL fields.
- Converts ISO-8601 formatted time strings into Ruby `Time` objects,
  when used as the type for our GraphQL arguments.

This allows our GraphQL API to have a standardized way that it presents time
and handles time inputs.

Example:

```ruby
field :reply_id, Types::GlobalIDType[Discussion]

def reply_id
  Gitlab::GlobalId.build(object, id: object.reply_id)
end
```6

### Global ID scalars

All of our [Global IDs](#global-ids) are custom scalars. They are
[dynamically created](https://gitlab.com/gitlab-org/gitlab/-/blob/45b3c596ef8b181bc893bd3b71613edf66064936/app/graphql/types/global_id_type.rb#L46)
from the abstract scalar class
[`Types::GlobalIDType`](https://gitlab.com/gitlab-org/gitlab/-/blob/45b3c596ef8b181bc893bd3b71613edf66064936/app/graphql/types/global_id_type.rb#L4).

## Testing

For testing mutations and resolvers, consider the unit of
test a full GraphQL request, not a call to a resolver. This allows us to
avoid tight coupling to the framework because such coupling makes
upgrades to dependencies much more difficult.

You should:

- Prefer request specs (either using the full API endpoint or going through
  `GitlabSchema.execute`) to unit specs for resolvers and mutations.
- Prefer `GraphqlHelpers#execute_query` and `GraphqlHelpers#run_with_clean_state` to
  `GraphqlHelpers#resolve` and `GraphqlHelpers#resolve_field`.

For example:

```ruby
field :reply_id, Types::GlobalIDType[Discussion]

def reply_id
  Gitlab::GlobalId.build(object, id: object.reply_id)
end
```7

### Writing unit tests (deprecated)

WARNING:
Avoid writing unit tests if the same thing can be tested with
a full GraphQL request.

Before creating unit tests, review the following examples:

- [`spec/graphql/resolvers/users_resolver_spec.rb`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/spec/graphql/resolvers/users_resolver_spec.rb)
- [`spec/graphql/mutations/issues/create_spec.rb`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/spec/graphql/mutations/issues/create_spec.rb)

### Writing integration tests

Integration tests check the full stack for a GraphQL query or mutation and are stored in
`spec/requests/api/graphql`.

For speed, consider calling `GitlabSchema.execute` directly, or making use
of smaller test schemas that only contain the types under test.

However, full request integration tests that check if data is returned verify the following
additional items:

- The mutation is actually queryable in the schema (was mounted in `MutationType`).
- The data returned by a resolver or mutation correctly matches the
  [return types](https://graphql-ruby.org/fields/introduction.html#field-return-type) of
  the fields and resolves without errors.
- The arguments coerce correctly on input, and the fields serialize correctly
  on output.

Integration tests can also verify the following items, because they invoke the
full stack:

- An argument or scalar's validations apply correctly.
- Logic in a resolver or mutation's [`#ready?` method](#correct-use-of-resolverready) applies correctly.
- An [argument's `default_value`](https://graphql-ruby.org/fields/arguments.html) applies correctly.
- Objects resolve successfully, and there are no N+1 issues.

When adding a query, you can use the `a working graphql query that returns data` and
`a working graphql query that returns no data` shared examples to test if the query renders valid results.

You can construct a query including all available fields using the `GraphqlHelpers#all_graphql_fields_for`
helper. This makes it more straightforward to add a test rendering all possible fields for a query.

If you're adding a field to a query that supports pagination and sorting,
visit [Testing](graphql_guide/pagination.md#testing) for details.

To test GraphQL mutation requests, `GraphqlHelpers` provides two
helpers: `graphql_mutation` which takes the name of the mutation, and
a hash with the input for the mutation. This returns a struct with
a mutation query, and prepared variables.

You can then pass this struct to the `post_graphql_mutation` helper,
that posts the request with the correct parameters, like a GraphQL
client would do.

To access the response of a mutation, you can use the `graphql_mutation_response`
helper.

Using these helpers, you can build specs like this:

```ruby
field :reply_id, Types::GlobalIDType[Discussion]

def reply_id
  Gitlab::GlobalId.build(object, id: object.reply_id)
end
```8

### Testing tips and tricks

- Become familiar with the methods in the `GraphqlHelpers` support module.
  Many of these methods make writing GraphQL tests easier.

- Use traversal helpers like `GraphqlHelpers#graphql_data_at` and
  `GraphqlHelpers#graphql_dig_at` to access result fields. For example:

  ```ruby
  result = GitlabSchema.execute(query)

  mr_iid = graphql_dig_at(result.to_h, :data, :project, :merge_request, :iid)