Naming Prosecution Mitigator

    @apollo/federation-subgraph-compatibility

    1.0.1 • Public • Published

    Apollo Federation Subgraph Compatibility Testing

    NPM Version Continuous Integration Join the community forum MIT License

    @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:
      -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
      --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")
      --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

    When creating supergraph using Docker, it will create network with default subgraph endpoint as http://localhost:4001. You can override the default endpoint by specifying custom GraphQL endpoint path and port.

    # 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

    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).

    Install

    npm i @apollo/federation-subgraph-compatibility

    DownloadsWeekly Downloads

    45

    Version

    1.0.1

    License

    MIT

    Unpacked Size

    21.8 kB

    Total Files

    12

    Last publish

    Collaborators

    • apollo-bot
    • dkuc