File Providers

Available file providers:

• Build Router from source
• Conditional
• Custom provider
• From command
• GitHub file
• GraphOS canned operations
• GraphOS canned operations by ID
• GraphOS supergraph Router URL overrides
• GraphOS subgraph SDL
• GraphOS subgraph names
• GraphOS supergraph SDL
• Inline file
• Inline directory
• Merge YAML
• GraphOS offline license
• Relative dir
• Relative path
• Required file
• Router download script
• Templated file

Build Router from source

A file provider used for building the Router from source at a specific git commit or reference. A profile and list of features can optionally be provided.

- name: "router-build.sh"
  env_var: ROUTER_BUILD_SCRIPT
  kind: build_router_from_source
  git_ref: "some-ref"
  rust_version: "1.89.0"
  profile: "release"
  features: "default"

Conditional

Conditionally run a file provider from an ordered list based on simple “where” clauses that make use of the provided templating variables. The first case with a “where” clause that holds will be run as the output of this provider.

Writing where clauses

The “where” clause on each case is a simple comparison against a single templating variable. You must include the var key which accepts a string variable name that is required to be defined within the test plan containing this provider. You may then assert that the variable is equal (eq) or not equal (ne) to a given scalar value.

If none of the provider where clauses match, this provider will error during static analysis checks.

- name: conditional_config.json
  env_var: CONDITIONAL_CONFIG
  kind: conditional
  cases:
    - where: { var: test_type, eq: load }
      kind: relative_path
      path: data/config-load.json

    - where: { var: test_type, eq: ramp }
      kind: relative_path
      path: data/config-ramp.json

Custom provider

Use a custom provider to execute a command and produce a set of files.

- name: "router-docker-compose"
  env_var: ROUTER_DOCKER_COMPOSE
  kind: custom_provider
  type: "router-docker-compose"
  graph_ref: "graph@variant"
  router_version: "v2.x.y"
  build_router_from_source: "false"

From command

Run a command provider and use its output as a file provider resource.

As with all other command providers, you can provide both environment variables and other file providers as inputs to the command being executed. RTF will use the contents of the $RTF_OUTPUT path as the output of this provider, supporting both writing a single file to that path and creating a directory at that path containing multiple files.

- name: vegeta-ops.json
  env_var: VEGETA_OPS
  kind: from_command
  command:
    name: format-for-vegeta.sh
    kind: relative_path
    path: scripts/format-for-vegeta.sh
  env_vars:
    ROUTER_URL: "http://127.0.0.1:4000/"
  file_providers:
    - name: canned_ops.json
      env_var: CANNED_OPS_FILE
      kind: graphos_canned_ops
      graph_ref: "my@graph"
      top_n: 20
      skip_mutations: true

format-for-vegeta.sh

#!/usr/bin/env sh
while read -r req; do
  if [[ "$OSTYPE" == "darwin"* ]]; then
    encoded=$(echo "$req" | base64 -b 0)
  else
    encoded=$(echo "$req" | base64 -w 0)
  fi
   
  jq -nc \
    --arg body "$encoded" \
    --arg url "$ROUTER_URL" \
    '{
      "body": $body,
      "header": { "Content-type": ["application/json"] },
      "method": "POST",
      "url": $url
    }' >> "$RTF_OUTPUT"
done <"$CANNED_OPS_FILE"

GitHub file

The user specifies a path to a file within a GitHub repository, optionally providing a specific ref of the repository to pull the file from. If no ref is providing then the provider will pull the version of the file found on the default branch.

- name: "my-file.txt"
  env_var: MY_FILE
  kind: github_file
  org: "my-org"
  repo: "my-repo"
  path: "resources/test-data/my-file.txt"
  git_ref: "some-ref"

GraphOS canned operations

The user specifies the graph ref and parameters that should be used to generate canned GraphQL requests based on operations data obtained from the GraphOS API.

- name: canned_ops.json
  env_var: CANNED_OPS_FILE
  kind: graphos_canned_ops
  graph_ref: graph@variant
  top_n: 10
  skip_mutations: true
  time_range: 7d

GraphOS canned operations by ID

The user specifies the graph ref and a set of operation IDs to be fetched from the GraphOS API for generating canned GraphQL requests.

- name: canned_ops.json
  env_var: CANNED_OPS_FILE
  kind: graphos_canned_ops_by_id
  graph_ref: graph@variant
  operation:
    kind: inline
    content: |
      5b1f8a2a1bd4be697559013a23fcbcb9186afe77
      3f56aa92aad650bbfc7ba481cbe029aba2f6c5f4
      50b77d7351052abd84dcd2c2ccb63eff2fa2f94c

GraphOS supergraph Router URL overrides

The user specifies the graph ref that should be used to fetch subgraph SDL files from the GraphOS API and generates a the override_subgraph_urls YAML snippet that can be merged into a router config file.

This should be used whenever subgraph requests need to be mapped to a mock server instead of hitting the real subgraph as defined in the supergraph, which is typically desirable behavior when working with real graphs.

- name: subgraph-url-overrides.yaml
  env_var: SUBGRAPH_URL_OVERRIDES
  kind: graphos_subgraph_router_url_overrides
  graph_ref: graph@variant
  url_format: localhost

GraphOS subgraph SDL

The user specifies the graph ref that should be used to fetch a subgraph SDL files from the GraphOS API.

Note that this file provider will output a directory of SDL schema files, one for each subgraph.

- name: "subgraphs"
  env_var: SUBGRAPHS
  kind: graphos_subgraphs
  graph_ref: graph@variant

GraphOS subgraph names

The user specifies the graph ref that should be used to fetch the names of subgraphs in the supergraph from the GraphOS API.

This file provider will output a newline-delimited file of the subgraph names.

- name: "subgraph_names"
  env_var: SUBGRAPH_NAMES
  kind: graphos_subgraph_names
  graph_ref: graph@variant

GraphOS supergraph SDL

The user specifies the ref that should be used to fetch a supergraph SDL file from the GraphOS API.

- name: "supergraph.graphql"
  env_var: SUPERGRAPH
  kind: graphos_supergraph
  graph_ref: graph@variant
  with_subgraph_overrides: docker

Inline file

The simplest form of file provider: the user specifies the contents of the file inline within their config file.

- name: "my-file.txt"
  env_var: MY_FILE
  kind: inline
  content: |
    my raw file content.
    specified inline within an RTF config file.

Inline directory

An inline representation of a directory of files. The environment variable will be set to the path of the directory itself. All files within that directory will need to be referenced using a combination of this environment variable and its path.

This file provider primarily exists so that other file providers that produce a directory of files can be converted into their inline representations.

If, as a user of RTF, you need to specify multiple inline files, we strongly advise you use an inline file provider for each file and that you DO NOT use this file provider.

- name: "my-directory"
  env_var: MY_DIRECTORY
  kind: inline_dir
  files:
    - path: file1.txt
      content: |
        content for file1
    - path: nested/file2.txt
      content: |
        content for file2

Merge YAML

Merge the YAML output of text based file providers into a single YAML file.

Matching keys in the overrides file will replace scalar values, concatenate arrays and merge keys for maps.

When merging a single overrides file the overrides provider can be specified directly under the overrides key:

- name: router-config.yaml
  env_var: ROUTER_CONFIG
  kind: merge_yaml
  base:
    kind: relative_path
    path: "data/base-router-config.yaml"
  overrides:
    kind: relative_path
    path: "../my-overrides.yaml"

When merging multiple overrides files, specify the providers in the order you want to merge them as an array:

- name: router-config.yaml
  env_var: ROUTER_CONFIG
  kind: merge_yaml
  base:
    kind: relative_path
    path: "data/base-router-config.yaml"
  overrides:
    - kind: relative_path
      path: "../my-overrides.yaml"
    - kind: relative_path
      path: "../my-other-overrides.yaml"

GraphOS offline license

The user specifies the graph id that should be used to fetch an offline license from the GraphOS API.

- name: license.jwt
  env_var: LICENSE
  kind: offline_graphos_license
  graph_id: graph

Relative dir

A relative path from the containing config file to a target directory and a list of files that should be made available as part of the test run. This provider works both with local directories and directories within GitHub if the containing config file was pulled from a repository.

The specified environment variable for this provider will point to the location of the directory itself. Relative paths under the specified directory will be maintained and in order to provided deterministic locations for each included file.

Only the specified files will be included and there is no way to wildcard multiple files.

- name: "my-data"
  env_var: MY_DATA
  kind: relative_dir
  path: "../../resources/test-data"
  files:
    - "my-file.txt"
    - "nested/my-nested-file.json"

Relative path

A relative path from the containing config file to a target file that should be made available as part of the test run. This provider works both with local files and files within GitHub if the containing config file was pulled from a repository.

- name: "my-file.txt"
  env_var: MY_FILE
  kind: relative_path
  path: "../../resources/test-data/my-file.txt"

Required file

The only purpose of this file provider is to throw an error if it still exists when the file providers are being checked. All definitions of a required file are expected to be replaced by user defined file providers.

- name: "router-config.yaml"
  env_var: ROUTER_CONFIG
  kind: required
  message: "you must specify a router config file to use"

Router download script

Produces a POSIX shell script that can be run in order to download a target version of the Apollo Router.

- name: "router-download.sh"
  env_var: ROUTER_DOWNLOAD
  kind: router_download_script
  version: "v2.6.0"

Templated file

Write a file whose content is an inline string with ${variable} patterns interpolated from the RTF template variables defined for the current run.

- name: config.json
  env_var: CONFIG_FILE
  kind: templated
  content: |
    { "endpoint": "${router_url}" }