Join us for GraphQL Summit, October 10-12 in San Diego. Use promo code ODYSSEY for $400 off your pass.
Launch GraphOS Studio
You're viewing documentation for a previous version of this software. Switch to the latest stable version.

Testing Workbench graphs locally

Apollo Workbench enables you to run a mocked version of any fully composing design on your local machine.

Starting and stopping

To start your mocked locally, click the triangular Play button that appears when hovering over the s row in the navigation panel:

Play button for running supergraph locally

To stop execution, click the square Stop button.

By default, the mocked gateway runs on port 4000. ports start with 4001 and increment by one (4002, etc.).

You can override these defaults by modifying your VS Code user settings (go to Extensions > Apollo-Workbench and click Edit in settings.json):

"apollo-workbench.gatewayPort": 4000,
"apollo-workbench.startingServerPort": 4001

You can only run one design at a time. Whenever you start a design, any other running design is stopped.

Defining custom mocks

You can define custom mocks for any in the same format Apollo Server expects for mocks. Access the custom mocks for any by right-clicking the subgraph name and selecting View Subgraph Custom Mocks:

Viewing custom mocks

Custom mocks are stored as raw strings in the apollo-workbench file and synced whenever changes are saved to the actual .js file. Valid JavaScript or TypeScript is required for an exported mocks.

How do mocks work in Workbench?

When you run your design, Workbench starts one Apollo Server instance for each mocked in the design. Each instance dynamically creates reference s for any entities that the subgraph defines. These resolvers are used in combination with any defined custom mocks to resolve incoming s.

Workbench also starts a separate Apollo Server instance to act as the gateway, using the @apollo/gateway library. This instance is passed the composed from your schemas.

When all server instances have started, Workbench opens Apollo Sandbox so you can execute s against the gateway.

Using non-mocked subgraphs

You can choose to mock some of your s while the rest of your s use actual GraphQL endpoint URLs. These URLs can be local or remote (such as the URL of a staging subgraph).

To specify a URL for a non-mocked , first open that subgraph's settings in Workbench:

Subgraph Workbench settings

Then do all of the following:

  1. Add a url option that specifies the 's URL.
  2. Set the mocks.shouldMock option to false.
  3. Save your changes.

Workbench does not verify whether a 's remote url is reachable.

Sending custom headers

Whenever Workbench communicates with a GraphQL endpoint (such as one of your staging s), it might need to provide custom HTTP headers that the endpoint requires.

You can provide these headers in a 's settings via the requiredHeaders option:

Setting custom subgraph headers

Syncing a subgraph's schema

Whenever you're running a Workbench design with non-mocked s, the s for those subgraphs might change at any time (for example, if a new subgraph version is deployed to staging).

To account for these changes, Workbench can sync your design's version of a 's with the version at its url.

To enable syncing, set the mocks.autoUpdateSchemaFromUrl option to true in your 's settings (this option is shown above in Using non-mocked subgraphs).

As long as syncing is enabled, Workbench regularly pings the 's url for updates while your design is running. Any schema updates are saved to the schema in the .apollo-workbench file.

Setting up Managed Federation
Exporting designs
Edit on GitHubEditForumsDiscord