add @mock spec

[magicmark]

see graphql/ai-wg#79

• 🚀 Rendered Spec: https://public.larah.me/~mark/MockSpec.html
• ✨ Demo: https://mock-spec-demo.larah.me/

Prior art! https://medium.com/airbnb-engineering/graphql-data-mocking-at-scale-with-llms-and-generatemock-30b380f12bd6

[rebello95]

Left some comments documenting our discussion earlier today, as well as a few other things I noticed 😄 Thanks for the hard work here!

[rebello95]

One thing that is probably worth noting here is that for a document to remain valid, the field removal likely needs to happen recursively:

• Empty selection sets are invalid, so if all fields within a selection set are marked with @mock, the parent field needs to be removed as well. Same goes for fragment definitions and inline fragments
• Unused variables are invalid, so if a @mocked field is the only field that used an argument, the argument needs to be removed from the root query
• An operation with no selection sets is invalid, @mocking all top-level fields should be disallowed (in favor of mocking the top-level operation itself)

[magicmark]

great points.

[rebello95]

Looks like these clarifications are still missing; maybe we add them to the next line?

[rebello95]

From our call today:

• Using schema coordinates here will not work for field aliases (since those don't exist in the schema)
• We need to know the path for which a given mock is being applied to (not only the type) in order to ensure it provides necessary data for all the required fields (see the example below - user-1 and user-2 variants represent the same type, but both would be invalid for the other's field path)
• To work around this, we propose changing __appliesTo__ to __path__ and changing its representation to be a path relative to the parent executable fragment/operation
• For @mock on the root query, __path__ could be . <root>, or something else

query SomeQuery {
  user(id: 123) @mock(variant: 'user-1') { # returns User
    name
  }
  house(id: 123) { # returns User
    owner @mock(variant: 'renter-1') {
      name
      avatarUrl
    }
  }
  somethingElseThatReturnsAUser @mock(variant: 'user-2') { # returns User
    password
  }
}

[magicmark]

Option 1

• @mock on a query root does __path__ = "Query"
• @mock within queries do __path__ = "Query.bar.baz"
• @mock within fragments do __path__ = "Foo.bar.baz" (where "Foo" is the name of the fragment)

this feels nice but also possibly redundant, given that the "Query." or "." prefix is already implied by the mock file name.

Option 2

Same as above but remove the "Query." prefix for mocks within an operation/fragment:

• @mock on a query root does __path__ = "Query"
• @mock within queries do __path__ = "bar.baz"
• @mock within fragments do __path__ = "bar.baz"

Given that response positions also do not use a "Query." prefix I guess I'll go with option 2, but happy to bikeshed on this.

[magicmark]

@benjie points out that https://github.com/graphql/graphql-wg/blob/main/rfcs/OperationExpressions.md is already a (proposed) thing we could use here instead.

[rebello95]

Option 2 seems reasonable to me 👍🏽

[rebello95]

It might be worth noting that this data will be automatically inserted within the root data key in the operation's response data. In other words, for a @mock on a root query, its entry would be this:

{
  "mock-id": {
    "data": {
      "business": {
        "name": "The Great British Bakery",
        "rating": 5.0
      }
    },
    ...
  },
}

not this:

{
  "mock-id": {
    "data": {
      "data" {
        "business": {
          "name": "The Great British Bakery",
          "rating": 5.0
        }
      }
    },
    ...
  },
}

[rebello95]

Great work on this! I read through the whole thing and mostly have small nits/comments. Overall this is coming together!

[rebello95]

Looks like these clarifications are still missing; maybe we add them to the next line?

[rebello95]

Would suggest mentioning that aliases should be used in __path__ when present

[rebello95]

Suggested change

	6. Write the updated mock file
	6. Write the updated mock file (do not modify other mocks in the file)

[rebello95]

Suggested change

	Look for the GraphQL schema in <repo_root>/schema.graphql to understand what
	Look for the GraphQL schema in <repo_root>/schema.graphqls to understand what

May want to consider removing the filename here since it's implementation-specific