Workflow Syntax ​

YAML ​

We choose YAML as a primary configuration format, because YAML files can be read and written by humans and machines. This allows you to write workflows by hand or generate them with code

Spec ​

version ​

Required. Workflow file version

name ​

Required. Workflow name

env ​

Optional. Environment Variables

env:
  host: example.com

Example: Using environment variables in steps

env:
  host: example.com
steps:
  - name: GET request
    http:
      url: https://${{env.host}}
      method: GET

config ​

Optional. Workflow config

config.continueOnFail ​

Optional. Continue workflow after step failed

config.concurrency ​

Optional. Tests concurrency setting. The default amount is ∞

config.http ​

Optional. HTTP-Client config

config.http.rejectUnauthorized ​

Optional. Reject if SSL certificate is invalid

config.http.baseURL ​

Optional. Base URL

config.http.http2 New ​

Optional. Enable http2 support

config.grpc ​

Optional. gRPC-Client config

config.grpc.proto ​

Optional. Pre-load gRPC Protos into the workflow

config.loadTest Unstable ​

Optional. Load-Testing configuration

config:
  loadTest:
    phases:
    - duration: 10
      arrivalRate: 1
    - duration: 20
      arrivalRate: 100
    check:
      p99:
      - lte: 500

config.loadTest.phases Unstable ​

Required. Load-Testing phases

config.loadTest.phases.[phase] Unstable ​

Required. Load testing phase

config.loadTest.phases.[phase].duration Unstable ​

Required. Load testing phase duration

config.loadTest.phases.[phase].arrivalRate Unstable ​

Required. Load testing phase arrival rate (requests per second)

config.loadTest.check Unstable ​

Optional. Load testing checks

check:
  p99:
    - lte: 500

config.loadTest.check.avg Unstable ​

Optional

config.loadTest.check.min Unstable ​

Optional

config.loadTest.check.max Unstable ​

Optional

config.loadTest.check.med Unstable ​

Optional

config.loadTest.check.p95 Unstable ​

Optional

config.loadTest.check.p99 Unstable ​

Optional

components ​

Optional. OpenAPI components

components.schemas ​

Optional. OpenAPI schemas

components.schemas.<schema> ​

Optional. OpenAPI schema

components:
  schemas:
    Post:
      type: object
      properties:
        userId:
          type: integer
          required: true
        id:
          type: integer
          required: true
        title:
          type: string
          required: true
        body:
          type: string
          required: true

components.credentials New ​

Optional. Reusable components.credentials

components.credentials:
  example:
    basic:
      username: hello
      password: world

components.credentials.<credential> New ​

Required. Credential

components.credentials.<credential>.basic New ​

Optional. Basic Auth

basic:
  username: hello
  password: world

components.credentials.<credential>.basic.username New ​

Required. Basic Auth username

components.credentials.<credential>.basic.password New ​

Required. Basic Auth password

components.credentials.<credential>.bearer New ​

Optional. Bearer Auth

bearer:
  token: hello world

components.credentials.<credential>.bearer.token New ​

Required. Bearer Auth token

components.credentials.<credential>.oauth New ​

Optional. OAuth

oauth:
  endpoint: "https://stepci.eu.auth0.com/oauth/token"
  client_id: ""
  client_secret: ""
  audience: ""

components.credentials.<credential>.oauth.endpoint New ​

Required. OAuth endpoint

components.credentials.<credential>.oauth.client_id New ​

Required. OAuth Client ID

components.credentials.<credential>.oauth.client_secret New ​

Required. OAuth Client Secret

components.credentials.<credential>.oauth.audience New ​

Optional. OAuth Client Audience

components.credentials.<credential>.certificate New ​

Optional. Client Certificate auth

certificate:
  ca: |
    content
  cert: |
    content
  key: |
    content

Can be files

certificate:
  ca:
    file: file.cert
  cert:
    file: file.cert
  key:
    file: file.key

components.credentials.<credential>.certificate.ca New ​

Optional. Client Certificate authority

Can be a file

components.credentials.<credential>.certificate.cert New ​

Optional. Client Certificate

Can be a file

components.credentials.<credential>.certificate.key New ​

Optional. Client Certificate Key

Can be a file

components.credentials.<credential>.certificate.passphrase New ​

Optional. Client Certificate passphrase

components.credentials.<credential>.tls New ​

Optional. TLS config

tls:
  rootCerts: |
    content
  privateKey: |
    content
  certChain: |
    content

Can be files:

tls:
  rootCerts:
    file: root.cert
  privateKey:
    file: key.cert
  certChain:
    file: chain.cert

components.credentials.<credential>.tls.rootCerts New ​

Optional. TLS root certificate

Can be a file

components.credentials.<credential>.tls.privateKey New ​

Optional. TLS private key

Can be a file

components.credentials.<credential>.tls.certChain New ​

Optional. TLS certificate chain

Can be a file

before ​

Optional. A single test to be executed by the runner before tests. Has the same structure as tests.<test>.

**Example: **

version: "1.1"
name: "`before` section example"
before:
  name: Before all
  steps: []
tests:
  example1:
    name: Test 1
    steps: []
  example2:
    name: Test 2
    steps: []

after ​

Optional. A single test to be executed by the runner after tests. Has the same structure as tests.<test>.

**Example: **

version: "1.1"
name: "`after` section example"
tests:
  example1:
    name: Test 1
    steps: []
  example2:
    name: Test 2
    steps: []
after:
  name: After all
  steps: []

tests ​

Optional. A list of tests to be executed by the runner

tests.<test> ​

Required. A test

Example: Checking Response Status

tests:
  example:
    steps:
      - name: GET request
        http:
          url: https://example.com
          method: GET
          check:
            status: 200

tests.<test>.name ​

Optional. Test name

tests.<test>.env ​

Optional. Environment Variables

tests:
  example:
    env:
      host: example.com

tests.<test>.testdata ​

Optional. Provide test data

Example: From csv file

testdata:
  file: testdata.csv

Example: From csv string

testdata:
  content: |
    username,password
    mish,ushakov

tests.<test>.testdata.content ​

Optional. Test data content

tests.<test>.testdata.file ​

Optional. Test data file

tests.<test>.testdata.options ​

Optional. Test data parsing options

testdata:
  options:
    delimiter: ","
    quote: "'"
    escape: '"'
    headers:
      - one
      - two

tests.<test>.testdata.options.delimiter ​

Optional. The delimiter that will separate columns

tests.<test>.testdata.options.quote ​

Optional. The character to use to quote fields that contain a delimiter

tests.<test>.testdata.options.escape ​

The character to used to escape quotes inside of a quoted field

tests.<test>.testdata.options.headers ​

Optional. The first row is always treated as headers. Otherwise, you can provide a list of headers

tests.<test>.steps ​

Required. A list of steps to be executed by runner

tests.<test>.steps.[step] ​

Required. The step to be executed

Example: Checking Response Status

steps:
  - name: GET request
    url: https://example.com
    http:
      method: GET
      check:
        status: 200

tests.<test>.steps.[step].id ​

Optional. Step id

tests.<test>.steps.[step].name ​

Optional. Step name

tests.<test>.steps.[step].if ​

Optional. Condition. For Syntax, see Filtrex Documentation

if: captures.title == "Example Domain"

Available objects ​

• captures
• env

tests.<test>.steps.[step].retries ​

Optional. Retries config

retries:
  count: 1
  interval: 1s

tests.<test>.steps.[step].retries.count ​

Optional. Amount of retries

tests.<test>.steps.[step].retries.interval ​

Optional. Interval between the retries

tests.<test>.steps.[step].http ​

Optional. HTTP Step

tests.<test>.steps.[step].http.url ​

Required. Request URL

tests.<test>.steps.[step].http.method ​

Required. Request method

tests.<test>.steps.[step].http.headers ​

Optional. Request headers

headers:
  Content-Type: application/json

tests.<test>.steps.[step].http.body ​

Optional. Request Body

body: |
  {
    "title": "Hello Step CI!",
    "body": "This is the body",
    "userId": 1
  }

File as a body

body:
  file: README.md

tests.<test>.steps.[step].http.params ​

Optional. Query Params

params:
  hello: world
  world: hello

tests.<test>.steps.[step].http.auth ​

Optional. Auth configuration

tests.<test>.steps.[step].http.auth.$ref ​

Optional. A reference to a credential specified in components.credentials section

tests.<test>.steps.[step].http.auth.basic ​

Optional. Basic Auth

auth:
  basic:
    username: hello
    password: world

tests.<test>.steps.[step].http.auth.basic.username ​

Required. Basic Auth username

tests.<test>.steps.[step].http.auth.basic.password ​

Required. Basic Auth password

tests.<test>.steps.[step].http.auth.bearer ​

Optional. Bearer Auth

auth:
  bearer:
    token: hello world

tests.<test>.steps.[step].http.auth.bearer.token ​

Required. Bearer Auth token

tests.<test>.steps.[step].http.auth.oauth New ​

Optional. OAuth

auth:
  oauth:
    endpoint: "https://stepci.eu.auth0.com/oauth/token"
    client_id: ""
    client_secret: ""
    audience: ""

tests.<test>.steps.[step].http.auth.oauth.endpoint New ​

Required. OAuth endpoint

tests.<test>.steps.[step].http.auth.oauth.client_id New ​

Required. OAuth Client ID

tests.<test>.steps.[step].http.auth.oauth.client_secret New ​

Required. OAuth Client Secret

tests.<test>.steps.[step].http.auth.oauth.audience New ​

Optional. OAuth Client Audience

tests.<test>.steps.[step].http.auth.certificate New ​

Optional. Client Certificate auth

auth:
  certificate:
    ca: |
      content
    cert: |
      content
    key: |
      content

Can be files

auth:
  certificate:
    ca:
      file: file.cert
    cert:
      file: file.cert
    key:
      file: file.key

tests.<test>.steps.[step].http.auth.certificate.ca New ​

Optional. Client Certificate authority

Can be a file

tests.<test>.steps.[step].http.auth.certificate.cert New ​

Optional. Client Certificate

Can be a file

tests.<test>.steps.[step].http.auth.certificate.key New ​

Optional. Client Certificate Key

Can be a file

tests.<test>.steps.[step].http.auth.certificate.passphrase New ​

Optional. Client Certificate passphrase

tests.<test>.steps.[step].http.cookies ​

Optional. Set Cookies. Once set, the cookies will be sent in consequent requests

cookies:
  wows: world

tests.<test>.steps.[step].http.json ​

Optional. Request JSON

json:
  title: Hello Step CI!
  body: This is the body
  userId: 1

tests.<test>.steps.[step].http.form ​

Optional. Form submission

form:
  email: hello@stepci.com

tests.<test>.steps.[step].http.formData ​

Optional. Multipart Form submission

Fields can include a file

formData:
  email: hello@stepci.com       # simple field value
  readme:
    file: README.md             # file attachment
  idDocument:
    file: password.pdf          # file attachment with specific content-type
    type: application/pdf
  personInfo:
    value: '{ "name": "john" }' # form field with specific content-type
    type: application/json

tests.<test>.steps.[step].http.graphql ​

Optional. GraphQL Data

graphql:
  query: |
    query Request {
      method
      url
      headers {
        key
        value
      }
    }
  variables:
    id: 1

tests.<test>.steps.[step].http.graphql.query ​

Optional. GraphQL query

tests.<test>.steps.[step].http.graphql.variables ​

Optional. GraphQL variables

tests.<test>.steps.[step].http.trpc New ​

Optional. tRPC request

tests.<test>.steps.[step].http.trpc.query.<procedure> New ​

Optional. tRPC query

trpc:
  query:
    greet: Hello

Query will be sent as a batch if it is an array

trpc:
  query:
    - greet: Hello
    - greet: Hello

tests.<test>.steps.[step].http.trpc.mutation.<procedure> New ​

Optional. tRPC mutation

trpc:
  mutation:
    addUser:
      name: Mish

tests.<test>.steps.[step].http.captures ​

Optional. Capture response values into named variables

captures:
  id:
    jsonpath: $.id
  username:
    cookie: user

tests.<test>.steps.[step].http.captures.<capture>.jsonpath ​

Optional. Capture JSONPath

captures:
  id:
    jsonpath: $.id

tests.<test>.steps.[step].http.captures.<capture>.xpath ​

Optional. Capture XPath

captures:
  id:
    xpath: //ID

tests.<test>.steps.[step].http.captures.<capture>.header ​

Optional. Capture a response Header

captures:
  type:
    header: Content-Type

tests.<test>.steps.[step].http.captures.<capture>.selector ​

Optional. Capture a HTML selector

captures:
  title:
    selector: h1

tests.<test>.steps.[step].http.captures.<capture>.cookie ​

Optional. Capture a cookie

captures:
  user:
    cookie: user

tests.<test>.steps.[step].http.captures.<capture>.regex ​

Optional. Capture a regex match

captures:
  title:
    regex: <title>(.*?)<\/title>

tests.<test>.steps.[step].http.captures.<capture>.body ​

Optional. Capture whole response body

captures:
  example:
    body: true

tests.<test>.steps.[step].http.check ​

Optional. Provide checks to validate responses

tests.<test>.steps.[step].http.check.status ​

Optional. Check status code

check:
  status: 200

tests.<test>.steps.[step].http.check.statusText ​

Optional. Check status text

check:
  statusText: OK

tests.<test>.steps.[step].http.check.redirected ​

Optional. Check redirection status

check:
  redirected: true

tests.<test>.steps.[step].http.check.redirects ​

Optional. Check redirects

check:
  redirects:
    - https://example.com/

tests.<test>.steps.[step].http.check.headers ​

Optional. Check headers

check:
  headers:
    Content-Type: application/json

tests.<test>.steps.[step].http.check.body ​

Optional. Check body

check:
  body: "Hello"

tests.<test>.steps.[step].http.check.json ​

Optional. Check JSON

check:
  json:
    hello: world

tests.<test>.steps.[step].http.check.schema ​

Optional. Check response against JSON Schema

check:
  schema:
    type: object
    properties:
      id:
        type: integer
        required: true

tests.<test>.steps.[step].http.check.jsonpath ​

Optional. Check JSONPath

check:
  jsonpath:
    $.id: 1

tests.<test>.steps.[step].http.check.xpath ​

Optional. Check XPath

check:
  xpath:
    //SUCCESS: false

tests.<test>.steps.[step].http.check.selectors ​

Optional. Check CSS selectors

check:
  selector:
    h1: "Example Domain"

tests.<test>.steps.[step].http.check.cookies ​

Optional. Check cookies

check:
  cookies:
    hello: world

tests.<test>.steps.[step].http.check.captures ​

Optional. Check captures

check:
  captures:
    id: 1

tests.<test>.steps.[step].http.check.sha256 ​

Optional. Check SHA-256 Hash (response)

check:
  sha256: "567cfaf94ebaf279cea4eb0bc05c4655021fb4ee004aca52c096709d3ba87a63"

tests.<test>.steps.[step].http.check.md5 ​

Optional. Check MD5 Hash (response)

check:
  md5: "567cfaf94ebaf279cea4eb0bc05c4655021fb4ee004aca52c096709d3ba87a63"

tests.<test>.steps.[step].http.check.size ​

Optional. Check response size (in bytes)

check:
  size: 1024

tests.<test>.steps.[step].http.check.requestSize ​

Optional. Check request size (in bytes)

check:
  requestSize: 1024

tests.<test>.steps.[step].http.check.bodySize ​

Optional. Check body size (in bytes)

check:
  bodySize: 1024

tests.<test>.steps.[step].http.check.performance ​

Optional. Performance Checking (in ms)

check:
  performance:
    firstByte:
      - lte: 200
    total:
      - lte: 500

tests.<test>.steps.[step].http.check.performance.wait ​

Optional

check:
  performance:
    wait: 20

tests.<test>.steps.[step].http.check.performance.dns ​

Optional

check:
  performance:
    dns: 20

tests.<test>.steps.[step].http.check.performance.tcp ​

Optional

check:
  performance:
    tcp: 20

tests.<test>.steps.[step].http.check.performance.tls ​

Optional

check:
  performance:
    tls: 20

tests.<test>.steps.[step].http.check.performance.request ​

Optional

check:
  performance:
    request: 20

tests.<test>.steps.[step].http.check.performance.firstByte ​

Optional

check:
  performance:
    firstByte: 20

tests.<test>.steps.[step].http.check.performance.download ​

Optional

check:
  performance:
    download: 20

tests.<test>.steps.[step].http.check.performance.total ​

Optional

check:
  performance:
    total: 20

tests.<test>.steps.[step].http.check.ssl ​

Optional. SSL Certificate Validation

check:
  ssl:
    valid: true
    signed: true
    daysUntilExpiration:
      - gte: 60

tests.<test>.steps.[step].http.check.ssl.valid ​

Optional

check:
  ssl:
    valid: true

tests.<test>.steps.[step].http.check.ssl.signed ​

Optional

check:
  ssl:
    signed: true

tests.<test>.steps.[step].http.check.ssl.daysUntilExpiration ​

Optional

check:
  ssl:
    daysUntilExpiration: 30

tests.<test>.steps.[step].http.check.co2 ​

Optional. Check co2 emissions of the response in grams

check:
  co2:
    - lte: 1

tests.<test>.steps.[step].http.followRedirects ​

Optional. Follow redirects. Enabled by default

tests.<test>.steps.[step].http.timeout ​

Optional. Request Timeout

tests.<test>.steps.[step].http.retries ​

Optional. Number of times to retry request on failure or timeout, default 0.

tests.<test>.steps.[step].grpc ​

Optional. gRPC Step

grpc:
  proto:
    - public/helloworld.proto
  host: 0.0.0.0:50051
  service: helloworld.Greeter
  method: SayHello
  data:
    name: world!
  check:
    jsonpath:
      $.message: Hello world!

tests.<test>.steps.[step].grpc.proto ​

Required. gRPC protocol buffer file path

tests.<test>.steps.[step].grpc.host ​

Required. gRPC server

tests.<test>.steps.[step].grpc.service ​

Required. gRPC service

tests.<test>.steps.[step].grpc.method ​

Required. gRPC method

tests.<test>.steps.[step].grpc.data ​

Required. gRPC payload

tests.<test>.steps.[step].grpc.metadata ​

Optional. gRPC metadata

tests.<test>.steps.[step].grpc.auth ​

Optional. gRPC auth config

tests.<test>.steps.[step].grpc.auth.$ref ​

Optional. A reference to a credential specified in components.credentials section

tests.<test>.steps.[step].grpc.auth.tls ​

Optional. gRPC auth TLS config

auth:
  tls:
    rootCerts: |
      content
    privateKey: |
      content
    certChain: |
      content

Can be files:

auth:
  tls:
    rootCerts:
      file: root.cert
    privateKey:
      file: key.cert
    certChain:
      file: chain.cert

tests.<test>.steps.[step].grpc.auth.tls.rootCerts ​

Optional. gRPC TLS root certificate

Can be a file

tests.<test>.steps.[step].grpc.auth.tls.privateKey ​

Optional. gRPC TLS private key

Can be a file

tests.<test>.steps.[step].grpc.auth.tls.certChain ​

Optional. gRPC TLS certificate chain

Can be a file

tests.<test>.steps.[step].grpc.timeout ​

Optional. Connection timeout (deadline)

tests.<test>.steps.[step].grpc.captures ​

Optional. Capture response values into named variables

captures:
  id:
    jsonpath: $.id

tests.<test>.steps.[step].grpc.captures.<capture>.jsonpath ​

Optional. Capture JSONPath

captures:
  id:
    jsonpath: $.id

tests.<test>.steps.[step].grpc.check ​

Optional. Provide checks to validate responses

tests.<test>.steps.[step].grpc.check.json ​

Optional. Check JSON

check:
  json:
    hello: world

tests.<test>.steps.[step].grpc.check.schema ​

Optional. Check response against JSON Schema

check:
  schema:
    type: object
    properties:
      id:
        type: integer
        required: true

tests.<test>.steps.[step].grpc.check.jsonpath ​

Optional. Check JSONPath

check:
  jsonpath:
    $.id: 1

tests.<test>.steps.[step].grpc.check.captures ​

Optional. Check captures

check:
  captures:
    id: 1

tests.<test>.steps.[step].grpc.check.size ​

Optional. Check response size (in bytes)

check:
  size: 1024

tests.<test>.steps.[step].grpc.check.performance ​

Optional. Performance Checking (in ms)

check:
  performance:
    total:
      - lte: 500

tests.<test>.steps.[step].grpc.check.performance.total ​

Optional

check:
  performance:
    total: 20

tests.<test>.steps.[step].grpc.check.co2 ​

Optional. Check co2 emissions of the response in grams

check:
  co2:
    - lte: 1

tests.<test>.steps.[step].sse ​

Optional. Server-Sent-Events step type

sse:
  url: http://localhost:8080
  timeout: 10000
  check:
    messages:
      - id: 'message1'
        jsonpath:
          $.hello: "world"
      - id: 'message2'
        body: "world"

tests.<test>.steps.[step].sse.url ​

Required. Server-Sent-Events URL

tests.<test>.steps.[step].sse.timeout ​

Optional. Server-Sent-Events connection timeout. Defaults to 10000

tests.<test>.steps.[step].sse.check ​

Optional. Server-Sent-Events checks

tests.<test>.steps.[step].sse.messages ​

Optional. Server-Sent-Events message checks

tests.<test>.steps.[step].sse.messages.[message] ​

Optional. Server-Sent-Events message check

tests.<test>.steps.[step].sse.messages.[message].jsonpath ​

Optional. Server-Sent-Events JSONPath message check

tests.<test>.steps.[step].sse.messages.[message].body ​

Optional. Server-Sent-Events JSON message check

tests.<test>.steps.[step].sse.messages.[message].body ​

Optional. Server-Sent-Events body message check

tests.<test>.steps.[step].sse.messages.[message].schema ​

Optional. Server-Sent-Events JSONSchema message check

tests.<test>.steps.[step].delay ​

Optional. Delay step type

- delay: 1s

tests.<test>.steps.[step].graphql ​

Optional. GraphQL step type

- graphql:
    url: https://echo.hoppscotch.io/graphql
    query: |
      query Request {
        method
      }
    variables:
      id: 1
    check:
      status: 200
      jsonpath:
        $.data.method: POST

Inherited from HTTP step type

tests.<test>.steps.[step].graphql.url ​

Optional. GraphQL URL

tests.<test>.steps.[step].graphql.query ​

Optional. GraphQL query string

tests.<test>.steps.[step].graphql.variables ​

Optional. GraphQL variables

tests.<test>.steps.[step].trpc ​

Optional. tRPC step type

- name: Query
  trpc:
    url: http://localhost:2022/trpc
    query:
      - greet:
          json:
            name: Mish
      - greet:
          json:
            name: Mish
    check:
      status: /^20/

Inherited from HTTP Step type

tests.<test>.steps.[step].trpc.query.<procedure> ​

Optional. tRPC query

trpc:
  query:
    greet: Hello

Query will be sent as a batch if it is an array

trpc:
  query:
    - greet: Hello
    - greet: Hello

tests.<test>.steps.[step].trpc.mutation.<procedure> ​

Optional. tRPC mutation

trpc:
  mutation:
    addUser:
      name: Mish

tests.<test>.steps.[step].plugin ​

Optional. Plugin step type

- name: Plugin
  plugin:
    id: "@yourcompany/plugin"
    params:
      hello: world
    check:
      reply: world

tests.<test>.steps.[step].plugin.id ​

Optional. Plugin id (npm package or local file)

tests.<test>.steps.[step].plugin.params ​

Optional. Plugin params

tests.<test>.steps.[step].plugin.check ​

Optional. Plugin checks