Apollo Federation Subgraph Compatibility Testing
@apollo/federation-subgraph-compatibility script is an NPM package that allows you to test given subgraph's implementation for compatibility against the Apollo Federation Subgraph Specification. This testing suite verifies various Federation features against subgraph implementation. See compatibility testing docs for details on the expected schema and the data sets as well as information about the executed tests.
Installation
Apollo Federation subgraph compatibility test script is published to NPM.
npm install --dev @apollo/federation-subgraph-compatibility
You can execute the script using NPX
# remote package
npx @apollo/federation-subgraph-compatibility --help
# package installed locally
npx fedtest --help
# package installed globally
fedtest --help
Usage
@apollo/federation-subgraph-compatibility test script starts a supergraph that consists of your subgraph implementation, two reference subgraphs and Apollo Router. Since script needs to manage multiple processes, you need to specify which process management technology should be used to run the tests. Currently script supports PM2 and Docker Compose.
npx fedtest --help
Usage: fedtest [options] [command]
Run Apollo Federation subgraph compatibility tests
Options:
-V, --version output the version number
-h, --help display help for command
Commands:
pm2 [options] Start supergraph using PM2
docker [options] Start supergraph using Docker Compose
help [options] [command] display help for command
PM2
PM2 is a Node based process manager. When tests are run using pm2 command, script will start the supergraph using Apollo Rover dev command.
npx fedtest pm2 --help
Usage: fedtest pm2 [options]
Start supergraph using PM2
Options:
--config <subgraph.config.js> optional PM2 configuration file
--debug debug mode with extra log info
--endpoint <url> subgraph endpoint
--failOnRequired boolean flag to indicate whether any failing required test should fail the script.
--failOnWarning boolean flag to indicate whether any failing test should fail the script.
--format <json|markdown> optional output file format (choices: "json", "markdown", default: "markdown")
-h, --help display help for command
--quiet suppress logging to minimum
--schema <schema.graphql> optional path to schema file, if omitted composition will fallback to introspection
If your subgraph is already up and running, you can run compatibility tests using PM2 by specifying --endpoint <url> option. This will create supergraph that uses introspection to read subgraph schema.
npx fedtest pm2 --endpoint http://localhost:8080/graphql
If you have a subgraph schema available, you can also specify it on the command line. Schema path can be absolute or relative to the current directory.
npx fedtest pm2 --endpoint http://localhost:8080/graphql --schema /path/to/schema.graphql
PM2 can also be used to start your subgraph. You can specify an ecosystem config file that contains information how to start your subgraph.
// simple PM2 subgraph config that starts Node application
module.exports = {
apps : [{
name : "subgraph product",
script : "index.js",
cwd: "/path/to/your/implementation"
}]
}
npx fedtest pm2 --endpoint http://localhost:8080/graphql --config /path/to/subgraph.config.js
Docker Compose
Docker Compose is a tool for running multi-container Docker applications. When tests are run using docker command, script will compose supergraph using Apollo Rover supergraph compose command and run standalone router image.
npx fedtest docker --help
Usage: fedtest docker [options]
Start supergraph using Docker Compose
Options:
--compose <docker-compose.yaml> Path to docker compose file
--debug debug mode with extra log info
--failOnRequired boolean flag to indicate whether any failing required test should fail the script.
--failOnWarning boolean flag to indicate whether any failing test should fail the script.
--format <json|markdown> optional output file format (choices: "json", "markdown", default: "markdown")
-h, --help display help for command
--path <path> GraphQL endpoint path (default: "")
--port <port> HTTP server port (default: "4001")
--quiet suppress logging to minimum
--schema <schema.graphql> Path to schema file
In order to run compatibility tests using docker command, you need to pass both compose file and subgraph schema file.
Paths to files can be absolute or relative to the current working directory.
npx fedtest docker --compose /path/to/docker-compose.yaml --schema /path/to/schema.graphql
Docker Compose file is a YAML configuration file that defines all services, networks and volumes necessary for running your application. For Apollo Federation compatibility tests we require you to define a service called products which should expose your GraphQL endpoint at http://localhost:4001.
services:
products:
# must be a relative path to the directory that will be used to run the tests
# if you are going to run the tests from the same directory as your docker file, then you can specify .
build: path/to/my-implementation
# expose ports
ports:
- 4001:4001
If your application exposes custom path (e.g. /graphql) or use different port, make sure to also specify those values as command line arguments.
# docker compose file starts subgraph exposing http://localhost:8080/graphql
npx fedtest docker --compose /path/to/docker-compose.yaml --schema /path/to/schema.graphql --path /graphql --port 8080
For compose file examples, see the example implementations in this repository. For additional details, please refer to the Docker compose documentation.
Test Results
Script logs the compatibility test results on the console and also generates corresponding results file. By default, script will generate results in a markdown format. You can change this behavior by specifying and --format json option.
# generate results.json file
npx fedtest pm2 --endpoint http://localhost:8080/graphql --format json
Debug Mode
In order to enable debug mode that provides more verbose logs, specify --debug option on the command line.
npx fedtest pm2 --endpoint http://localhost:8080/graphql --debug
Contact
If you have a specific question about the testing library or code, please start a discussion in the Apollo community forums.
Security
For more info on how to contact the team for security issues, see our Security Policy.
License
This library is licensed under The MIT License (MIT).