graphql-to-karate 🚀

Project Status: v0.2.0 release. The project is still in its early stages. To report a bug, feel free to open an issue.

🎯 About The Project

Automagically generate Karate API tests from your GraphQL schemas. Useful for test-driven development, change validation in CI/CD, and more.

📢 Demonstration

graphql-to-karate.mp4

✨ Features

Here are some features that this tool provides:

• Generate API tests from GraphQL schemas: Karate API test generation for both Query and Mutation operations is supported.
• Filterable Query and Mutation operations: Allows you to filter down and generate tests for a specific subset of target operations.
• Validate response codes and response shapes: Validates response codes and response schemas using Karate schema validation.
• Handles cyclical type relationships: Prunes cyclical types to remove cycles as they are encountered.
• Supports custom scalar types: Custom scalar types may be optionally mapped to their corresponding Karate schema types.
• Generates test data for arguments and input types: Test data for query arguments and input types is generated automatically.
• Interactive and non-interactive CLI modes: Supports both interactive and non-interactive CLI modes, as well as JSON configuration.
• Federation-specific directives: Supports some federation-specific directives, like @inaccessible and @external.

See the full list of available options below for more information.

🤖 Installation

📥 Binary Releases

Head over to releases and download the latest binary for your specific platform. If a binary for your platform is not available, see the Package Manager or Building From Source sections below.

📦 Package Manager

graphql-to-karate is also available as a NuGet offering and can be installed with the following command:

dotnet tool install --global graphql-to-karate --version 0.2.0

🛠️ Building From Source

To build from source, clone the repository locally and run some flavor of the following command. Be sure to update <runtime identifier> to your target platform. A catalog of available runtime identifiers can be viewed here.

dotnet publish src/GraphQLToKarate.CommandLine/GraphQLToKarate.CommandLine.csproj \
  --configuration Release \
  --runtime <runtime identifier> \
  --output ./publish \
  --self-contained true \
  --force \
  /p:PublishReadyToRun=true \
  /p:PublishSingleFile=true \
  /p:TreatWarningsAsErrors=false

Once published, you can move the binary to your preferred install location to use.

🌌 Usage

To use graphql-to-karate, simply invoke the graphql-to-karate convert command, passing your GraphQL schema file as an argument:

graphql-to-karate convert my-schema.graphql

By default, you will be walked through conversion in an interactive way within the CLI.

A --non-interactive option as well as JSON configuration are also available (see full Command Options below), which may be useful in CI/CD environments.

📖 Examples of Non-Interactive Invokation

Using Command-Line Options

graphql-to-karate convert my-schema.graphql \
  --non-interactive \
  --base-url "https://my-api.com" \
  --custom-scalar-mapping DateTime:string,Long:number,Float:number,URL:string \
  --query-operation-filter Users,UserById \
  --output-file some-api.feature\

Using a JSON configuration

graphql-to-karate convert my-schema.graphql --non-interactive --configuration-file config.json

This flavor of graphql-to-karate usage is used within CI/CD validation for this repository, where a mock GraphQL server is spun up, graphql-to-karate converts the GraphQL schema to a Karate API test, and then the generated Karate API test is run. The JSON configuration file used can be found here. Check out the full workflow here.

📝 Convert Command Options

OPTION	DEFAULT	ABOUT
-h, --help		Prints help information
--log-level	Information	Minimum level for logging
--non-interactive	false	Whether to run conversion in a non-interactive way or not
--output-file	graphql.feature	The output file to write the Karate feature to
--query-name	Query	The name of the GraphQL query type
--mutation-name	Mutation	The name of the GraphQL mutation type
--exclude-queries	false	Whether to exclude queries from the Karate feature or not
--include-mutations	false	Whether to include mutations in the Karate feature or not
--base-url	"https://your-awesome-api.com"	The base URL to be used in the Karate feature
--custom-scalar-mapping		The path or raw value custom scalar mapping
--query-operation-filter		A comma-separated list of GraphQL query operations to include in the Karate feature. If empty, all query operations will be included
--mutation-operation-filter		A comma-separated list of GraphQL mutation operations to include in the Karate feature. If empty, all mutation operations will be included
--type-filter		A comma-separated list of GraphQL types to include in the Karate feature. If empty, all types will be included
--configuration-file		The path of the configuration file

🗺️ Roadmap

See the open issues for a list of proposed features (and known issues).

🤝 Contributing

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated. For detailed contributing guidelines, please see the CONTRIBUTING docs.

📜 License

Distributed under the MIT License License. See LICENSE for more information.

Contact

@wbaldoumas

Project Link: https://github.com/wbaldoumas/graphql-to-karate