{"id":13564117,"url":"https://github.com/IBM/graphql-query-generator","last_synced_at":"2025-04-03T21:30:25.183Z","repository":{"id":37727086,"uuid":"261555063","full_name":"IBM/graphql-query-generator","owner":"IBM","description":"Randomly generates GraphQL queries from a GraphQL schema","archived":false,"fork":false,"pushed_at":"2023-01-06T07:40:00.000Z","size":2172,"stargazers_count":341,"open_issues_count":43,"forks_count":26,"subscribers_count":12,"default_branch":"master","last_synced_at":"2025-03-19T00:07:43.245Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/IBM.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-05-05T18:41:38.000Z","updated_at":"2025-03-11T09:20:15.000Z","dependencies_parsed_at":"2023-02-05T15:46:44.970Z","dependency_job_id":null,"html_url":"https://github.com/IBM/graphql-query-generator","commit_stats":null,"previous_names":[],"tags_count":14,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/IBM%2Fgraphql-query-generator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/IBM%2Fgraphql-query-generator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/IBM%2Fgraphql-query-generator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/IBM%2Fgraphql-query-generator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/IBM","download_url":"https://codeload.github.com/IBM/graphql-query-generator/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247082776,"owners_count":20880716,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-01T13:01:26.747Z","updated_at":"2025-04-03T21:30:24.511Z","avatar_url":"https://github.com/IBM.png","language":"TypeScript","funding_links":[],"categories":["TypeScript","others"],"sub_categories":[],"readme":"![GitHub last commit](https://img.shields.io/github/last-commit/ibm/graphql-query-generator.svg?style=flat) [![npm](https://img.shields.io/npm/v/ibm-graphql-query-generator.svg?style=flat)](https://www.npmjs.com/package/ibm-graphql-query-generator)\n\n# GraphQL Query Generator\n\nThis library will generate randomized [GraphQL](https://graphql.org/) queries from a given schema.\n\n![](./images/diagram.png)\n\nIt can be used in a few ways:\n\n- _Engineering_: If you operate a GraphQL service, you might use this library to:\n  - develop a static test suite of GraphQL queries\n  - develop a battery of queries to test the effect of performance improvements\n- _Scientific_: Understand the characteristics of various GraphQL services\n\n## Usage\n\nInstall the library using:\n\n```\nnpm i ibm-graphql-query-generator\n```\n\nUsage typically relies on the `generateRandomQuery` function, which can be imported like this:\n\n```javascript\nconst { generateRandomQuery } = require(\"ibm-graphql-query-generator\")\n```\n\n### Minimal working example\n\nAll [arguments](https://facebook.github.io/graphql/draft/#sec-Language.Arguments) are exposed as [variables](https://facebook.github.io/graphql/draft/#sec-Language.Variables). _Providers_ can be passed to provide values for these variables. For example:\n\n```javascript\nconst { generateRandomQuery } = require(\"ibm-graphql-query-generator\")\n\nconst { buildSchema, print } = require(\"graphql\")\n\nconst schema = `\n  type Query {\n    getUser(name: String!): User\n    getCompany(companyName: String!): Company\n  }\n\n  type User {\n    firstName: String\n    lastName: String\n    employer: Company\n    friends: [User]\n  }\n\n  type Company {\n    name: String\n    CEO: User\n    employees: [User]\n  }\n`\n\nconst configuration = {\n  depthProbability: 0.5,\n  breadthProbability: 0.5,\n  providerMap: {\n    \"*__*__name\": () =\u003e {\n      const nameList = [\"Alfred\", \"Barbara\", \"Charles\", \"Dorothy\"]\n\n      return nameList[Math.floor(Math.random() * nameList.length)]\n    },\n    \"*__*__companyName\": () =\u003e {\n      const companyNameList = [\n        \"All Systems Go\",\n        \"Business Brothers\",\n        \"Corporate Comglomerate Company\",\n        \"Data Defenders\"\n      ]\n\n      return companyNameList[\n        Math.floor(Math.random() * companyNameList.length)\n      ]\n    }\n  }\n}\n\nconst { queryDocument, variableValues, seed } = generateRandomQuery(\n  buildSchema(schema),\n  configuration\n)\n\nconsole.log(print(queryDocument))\nconsole.log(variableValues)\n```\n\n## Example configurations\n\nWe provide sample query generators for the following APIs:\n\n- [GitHub API](https://github.com/IBM/graphql-query-generator/tree/master/examples/github-query-generator)\n- [Yelp API](https://github.com/IBM/graphql-query-generator/tree/master/examples/yelp-query-generator)\n\n## Generating random queries\n\nThis library exposes two functions for generating random GraphQL queries:\n\n- `getRandomQuery(schema: GraphQLSchema, config: Configuration)`: Produces a random query from the given schema, and considering the passed configuration.\n- `getRandomMutation(schema: GraphQLSchema, config: Configuration)`: Produces a random mutation from the given schema, and considering the passed configuration.\n\n### Configuration\n\nFunctions of this library accept a configuration object with the following properties:\n\n- `depthProbability` (type: `number`, default: `0.5`): The probability (from `0` to `1`) that, if existent, fields that themselves have subfields are selected at every level of the generated query. The number of so selected fields depends on the `breadthProbability`.\n- `breadthProbability` (type: `number`, default: `0.5`): The probability (from `0` to `1`) that a field (nested or flat) is selected at every level of the generated query.\n- `maxDepth` (type: `number`, default: `5`): The maximum depths of the query / mutation to generate. This library ensures that leave nodes do not require children fields to be selected.\n- `ignoreOptionalArguments` (type: `boolean`, default: `true`): If set to `true`, non-mandatory arguments will not be included in the generated query / mutation.\n- `argumentsToIgnore` (type: `string[]`, default: `[]`): List of argument names that should be ignored in any case. If non-null arguments are configured to be ignored, an error will be thrown.\n- `argumentsToConsider` (type: `string[]`, default: `[]`): List of argument names that should be considered, even if the argument is optional and `ignoreOptionalArguments` is set to `true`.\n- `providerMap` (type: `{[varNameQuery: string]: any | ProviderFunction }`, default: `{}`): Map of values or functions to provide values for the variables present in the generated query / mutation. See details below.\n- `providePlaceholders` (type: `boolean`, default: `false`): If enabled, instead of defaulting to `null`, placeholder values of correct type are provided for variables. Specifically, the placeholders are `10` for type `Int`, `10.0` for type `Float`, `true` for type `Boolean`, and `\"PLACEHOLDER\"` for types `String` and `ID`, and custom scalars.\n- `considerInterfaces` (type: `boolean`, default: `false`): Create queries containing interfaces (by calling fields in the interfaces and/or creating fragments on objects implementing the interfaces)\n- `considerUnions` (type: `boolean`, default: `false`): Create queries containing unions (by creating fragments on objects of the unions)\n- `seed` (type: `number`, optional): Allows the generator to produce queries deterministically based on a random number generator seed. If no seed is provided, a random seed will be provided. The seed that is used to produce the query, whether user-provided or randomly generated, will be included in the output.\n- `pickNestedQueryField` (type: `boolean`, default: `false`): Guarantees that the generator will pick at least one nested field.\n\nExample:\n\n```javascript\nconst cfg = {\n  'depthProbability':        0.5,\n  'breadthProbability':      0.5,\n  'maxDepth':                5,\n  'ignoreOptionalArguments': true,\n  'argumentsToIgnore':       [],\n  'argumentsToConsider':     [],\n  'providerMap':             {'*__*__*': null},\n  'considerInterfaces':      false,\n  'considerUnions':          false,\n  'seed':                    1,\n  'pickNestedQueryField':    false\n}\n```\n\n### Provider map\n\nWhenever a randomly generated query or mutation requires an [argument](https://facebook.github.io/graphql/draft/#sec-Language.Arguments), this library exposes that argument as a [variable](https://facebook.github.io/graphql/draft/#sec-Language.Variables). The names of these variables reflect the type and field that the argument applies to, as well as the argument name like so:\n\n```\n\u003ctype\u003e__\u003cfieldName\u003e__\u003cargumentName\u003e\n```\n\nAlternatively, you can match using:\n\n```\n\u003ctype\u003e__\u003cfieldName\u003e\n```\n\nIn this case, the provider function returns an object where multiple arguments are present.\n\nThe `providerMap` contains values or value producing functions for the variables in a query.\n\nThe keys of the `providerMap` are either the exact name of the variable or a wildcard where either the `type`, `fieldName`, and/or `argumentName` are replaced by a `*`. For example, the key `*__*__limit` matches all variables for arguments of name `limit`, no matter for what field the argument is used or in which type. If no `providerMap` is passed, a default map `{'*__*__*': null}` is used, which provides a `null` value to all variables (Note: this can be problematic if an argument defines a [non-null](https://facebook.github.io/graphql/draft/#sec-Type-System.Non-Null) value).\n\nThe values of the `providerMap` are either the concrete argument values, or a function that will be invoked to provide that value. A provider function will get passed a map of all already provided variable values, which allows to provide values based on previous ones. It will also get passed the argument type (as a `GraphQLNamedType`) as a second argument.\n\nThis library also exposes a function `matchVarName(query: string, candidates: string[]): string` that, from a given list of variable names and/or variable name queries, finds the one matching the given variable name or query.\n\nNote that for variables with an [enumeration type](https://graphql.org/learn/schema/#enumeration-types), this library automatically chooses one value at random.\n\n### Errors\n\nGenerating random queries or mutations may fail in some cases:\n\n- An error is thrown if a query hits the defined `maxDepth`, but there are only fields with children to choose from. Choosing such a field but then not choosing a sub-field for it (due to the `maxDepth` constraint) would result in an invalid query and thus causes this library to throw an error.\n- An error is thrown if there is no provider defined for a variable in the generated query.\n\n## Citing this library\n\nIf you use this library in a scientific publication, please cite:\n\n1. The library, as: _IBM, graphql-query-generator, 2020. https://github.com/IBM/graphql-query-generator_.\n2. The work in which we introduced it, as: _Cha, Wittern, Baudart, Davis, Mandel, and Laredo. A Principled Approach to GraphQL Query Cost Analysis. ESEC/FSE 2020_.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FIBM%2Fgraphql-query-generator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FIBM%2Fgraphql-query-generator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FIBM%2Fgraphql-query-generator/lists"}