XanoScript for Tests

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

// <what this test does>
<test|workflow_test> <test_name> {
  ...
}

Element	Required	Description
`test_type`	✅	Declares the test primitive type (`test` or `workflow_test`).
`test_name`	✅	The unique name for the test.
`description`	no	A short summary of the test. May also appear as a “//” comment above the block.

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

// Tests whether a user can log in and be issued an auth token successfully
test "test successful login" {
  datasource = "live"
  input = {email: "chris@xano.com", 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

// Tests login and incorrect password flow.
workflow_test "Basic user actions" {
  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

// Tests whether a user can log in and be issued an auth token successfully.
test "test successful login" {
  datasource = "live"
  input = {email: "chris@xano.com", password: "********"}
  // ... expectations
}

Workflow Test Configuration:

XanoScript

// Tests login and incorrect password flow.
workflow_test "Basic user actions" {
  // ... 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.

Setting	Type	Required	Description
`description`	string	no	A short summary of the test. May also appear as a “//” comment above the block.
`datasource`	string	no	Specifies which datasource to use for testing.
`input`	object	no	Test input data (unit tests only).
`tags`	array[string]	no	A 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

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

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

Workflow Test Example

XanoScript

// Tests login and incorrect password flow.
workflow_test "Basic user actions" {
  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.

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.

Start

AI

References

Introduction

Anatomy

Declaration

Test Types

Unit Tests

Workflow Tests

Section 1: Configuration

Section 2: Stack/Input

Section 3: Expectations

Settings

Detailed Examples

Unit Test Examples

Workflow Test Example

What’s Next

Explore the function reference

Try it out in VS Code

Learn about APIs

​Introduction

​Anatomy

​Declaration

​Test Types

​Unit Tests

​Workflow Tests

​Section 1: Configuration

​Section 2: Stack/Input

​Section 3: Expectations

​Settings

​Detailed Examples

​Unit Test Examples

​Workflow Test Example

​What’s Next

Explore the function reference

Try it out in VS Code

Learn about APIs

Introduction

Anatomy

Declaration

Test Types

Unit Tests

Workflow Tests

Section 1: Configuration

Section 2: Stack/Input

Section 3: Expectations

Settings

Detailed Examples

Unit Test Examples

Workflow Test Example

What’s Next