Skip to main content

​
Introduction

Tests in XanoScript allow you to define automated testing for your application logic. Unlike other primitives, tests come in two different types, each serving different testing purposes. XanoScript supports two types of tests:
  • Unit tests — Test a single function stack or primitive
  • Workflow tests — Test multiple functions or APIs together in sequence
Unit tests are embedded within the primitive they’re testing, while workflow tests are standalone primitives that can test complex multi-step scenarios.

​
Anatomy

Every XanoScript test follows a predictable structure, though the specific components vary by test type. Here’s a quick visual overview of the main building blocks — from declaration at the top to expectations at the bottom.

You can find more detail about each section by continuing below.

​
Declaration

Every test starts with a declarative header that specifies its type, name, and description.
XanoScript
<test|workflow_test> <test_name> {
description = "<what this test does>"
...
}
ElementRequiredDescription
test_type✅Declares the test primitive type (test or workflow_test).
test_name✅The unique name for the test.
descriptionnoOptional human-readable description of the test’s purpose.

​
Test Types

​
Unit Tests

Unit tests are embedded within the primitive they’re testing and focus on testing a single function stack or API endpoint.
XanoScript
test "test successful login" {
  description = "Tests whether a user can log in and be issued an auth token successfully"
  datasource = "live"
  input = {email: "chris@xano.com", password: "password"}
  expect.to_be_defined ($response.authToken)
}
Unit Test Characteristics:
  • Embedded — Live inside the primitive being tested
  • Single focus — Tests one function stack or API
  • Simple input — Uses direct input values
  • Response testing — Tests the response from the primitive

​
Workflow Tests

Workflow tests are standalone primitives that can test multiple functions or APIs together in sequence.
XanoScript
workflow_test "Basic user actions" {
  description = "Tests login and incorrect password flow"
  stack {
    api.call auth/login verb=POST {
      api_group = "Authentication"
      input = {email: "chris@xano.com", password: "password"}
    } as $endpoint1
    expect.to_be_defined ($endpoint1.authToken)
    // ... more test steps
  }
  tags = ["user actions"]
}
Workflow Test Characteristics:
  • Standalone — Independent primitive
  • Multi-step — Can test multiple functions/APIs in sequence
  • Complex logic — Uses full stack with multiple operations
  • Sequential testing — Tests can build on previous results

​
Section 1: Configuration

The configuration section defines how the test should run and what data to use.
Unit Test Configuration:
XanoScript
test "test successful login" {
  description = "Tests whether a user can log in and be issued an auth token successfully"
  datasource = "live"
  input = {email: "chris@xano.com", password: "password"}
  // ... expectations
}
Workflow Test Configuration:
XanoScript
workflow_test "Basic user actions" {
  description = "Tests login and incorrect password flow"
  // ... stack and expectations
  tags = ["user actions"]
}
Configuration Options:
  • datasource — Specifies which datasource to use for testing ("live", "draft", etc.)
  • input — Test input data (unit tests only)
  • tags — Categorization tags (workflow tests only)

​
Section 2: Stack/Input

This section varies significantly between test types.
Unit Test Input:
XanoScript
input = {email: "chris@xano.com", password: "password"}
Workflow Test Stack:
XanoScript
stack {
  api.call auth/login verb=POST {
    api_group = "Authentication"
    input = {email: "chris@xano.com", password: "password"}
  } as $endpoint1
  
  expect.to_be_defined ($endpoint1.authToken)
  
  api.call auth/login verb=POST {
    api_group = "Authentication"
    input = {
      email   : "incorrect@user.com"
      password: "incorrect Password"
    }
  } as $endpoint2
  
  expect.to_not_be_defined ($endpoint2.authToken)
}
Key Differences:
  • Unit tests use simple input objects
  • Workflow tests use full stack blocks with multiple operations
  • Workflow tests can call APIs, functions, and other primitives
  • Workflow tests can test multiple scenarios in sequence

​
Section 3: Expectations

The expectations section defines what the test should verify.
Expectation Syntax:
XanoScript
expect.to_be_defined ($response.authToken)
expect.to_not_be_defined ($endpoint2.authToken)
Common Expectation Methods:
  • expect.to_be_defined — Verifies a value exists and is not null/undefined
  • expect.to_not_be_defined — Verifies a value is null/undefined
  • expect.to_equal — Verifies a value equals an expected result
  • expect.to_not_equal — Verifies a value does not equal an expected result
  • expect.to_contain — Verifies a value contains expected content
  • expect.to_be_true — Verifies a value is true
  • expect.to_be_false — Verifies a value is false
Expectation Placement:
  • Unit tests — Expectations are defined after the input configuration
  • Workflow tests — Expectations can be placed anywhere in the stack

​
Settings

Test primitives support optional settings for organization and configuration.
SettingTypeRequiredDescription
descriptionstringnoA human-readable description of the test’s purpose.
datasourcestringnoSpecifies which datasource to use for testing.
inputobjectnoTest input data (unit tests only).
tagsarray[string]noA list of tags used to categorize and organize the test.
Datasource Options:
  • "live" — Uses the live datasource for testing
  • "draft" — Uses the draft datasource for testing
  • Other datasource names as configured in your workspace

​
Detailed Examples

​
Unit Test Examples

XanoScript
test "test successful login" {
  description = "Tests whether a user can log in and be issued an auth token successfully"
  datasource = "live"
  input = {email: "chris@xano.com", password: "password"}
  expect.to_be_defined ($response.authToken)
}

test "Incorrect password flow" {
  description = "Tests to ensure users are not issued an auth token on an incorrect password entry"
  datasource = "live"
  input = {
    email   : "chris@xano.com"
    password: "incorrectpassword"
  }
  expect.to_not_be_defined ($response.authToken)
}

​
Workflow Test Example

XanoScript
workflow_test "Basic user actions" {
  description = "Tests login and incorrect password flow"
  stack {
    api.call auth/login verb=POST {
      api_group = "Authentication"
      input = {email: "chris@xano.com", password: "password"}
    } as $endpoint1
  
    expect.to_be_defined ($endpoint1.authToken)
    
    api.call auth/login verb=POST {
      api_group = "Authentication"
      input = {
        email   : "incorrect@user.com"
        password: "incorrect Password"
      }
    } as $endpoint2
  
    expect.to_not_be_defined ($endpoint2.authToken)
  }

  tags = ["user actions"]
}

​
What’s Next

Now that you understand how to define tests in XanoScript, here are a few great next steps:

Explore the function reference

Learn about the built-in functions available in the stack to start writing more complex test logic.
https://mintlify.s3.us-west-1.amazonaws.com/xano-997cb9ee/images/vscode.svg

Try it out in VS Code

Use the XanoScript VS Code extension with Copilot to write XanoScript in your favorite IDE.

Learn about APIs

Create APIs that you can test with your unit and workflow tests to ensure robust functionality.
⌘I