QuadrastackQuadrastack
Documentation

Docs

Your First API Test

Complete beginner tutorial for testing JSONPlaceholder API with GET and POST requests, assertions, and variables.

Your First API Test

In this tutorial, you'll learn the fundamentals of API testing with Quadrastack by testing the public JSONPlaceholder API. You'll write GET and POST requests, add assertions, and use variables.

Time: 10 minutes | Level: Beginner

What You'll Build

By the end of this tutorial, you'll have a working test suite that:

  • Fetches a list of users (GET request)
  • Creates a new user (POST request)
  • Validates responses with assertions
  • Uses variables for flexibility

Prerequisites

Step 1: Create Your Project Directory

Create a new directory for your API tests:

mkdir my-first-api-test
cd my-first-api-test

Step 2: Write Your First GET Request

Create a file called requests.yaml and add your first request:

requests:
  get-users:
    method: GET
    url: https://jsonplaceholder.typicode.com/users

This is the simplest possible request. Let's run it:

quadrastack

Expected Output:

✓ get-users (200 OK, 245ms)

The CLI found your requests.yaml file, executed the request, and confirmed it returned a 200 status.

Step 3: Add Response Assertions

Now let's verify the response data. Update your requests.yaml:

requests:
  get-users:
    method: GET
    url: https://jsonplaceholder.typicode.com/users
    expect:
      status: 200
      body:
        $: type array
        $.length: "> 0"
        $[0].id: exists
        $[0].name: !empty
        $[0].email: matches "^[\\w.]+@[\\w.]+"

What these assertions do:

  • status: 200 - Verify successful response
  • $: type array - Root response must be an array
  • $.length: "> 0" - Array must have at least one item
  • $[0].id: exists - First user must have an ID
  • $[0].name: !empty - Name must not be empty
  • $[0].email: matches "..." - Email must match pattern

Run again:

quadrastack

Expected Output:

✓ get-users (200 OK, 238ms)
  ✓ status: 200
  ✓ body.$.type: array
  ✓ body.$.length: > 0
  ✓ body.$[0].id: exists
  ✓ body.$[0].name: !empty
  ✓ body.$[0].email: matches pattern

All assertions passed!

Step 4: Add a POST Request

Let's create a new user. Add this to your requests.yaml:

requests:
  get-users:
    method: GET
    url: https://jsonplaceholder.typicode.com/users
    expect:
      status: 200
      body:
        $: type array
        $.length: "> 0"
        $[0].id: exists
        $[0].name: !empty
        $[0].email: matches "^[\\w.]+@[\\w.]+"

  create-user:
    method: POST
    url: https://jsonplaceholder.typicode.com/users
    headers:
      Content-Type: application/json
    body:
      name: "Jane Doe"
      email: "jane.doe@example.com"
      phone: "123-456-7890"
    expect:
      status: 201
      body:
        $.id: exists
        $.name: "Jane Doe"
        $.email: "jane.doe@example.com"

Key points:

  • method: POST - HTTP POST for creating resources
  • headers - Set Content-Type for JSON
  • body - Request body as YAML (converted to JSON)
  • expect.status: 201 - Verify "Created" status

Run both tests:

quadrastack

Expected Output:

✓ get-users (200 OK, 242ms)
✓ create-user (201 Created, 318ms)

Step 5: Use Variables for Flexibility

Let's make our tests more flexible with variables. Create a new file called vars.yaml:

vars:
  default:
    baseUrl: "https://jsonplaceholder.typicode.com"
    userName: "Jane Doe"
    userEmail: "jane.doe@example.com"

  local:
    baseUrl: "http://localhost:3000"
    userName: "Test User"
    userEmail: "test@localhost"

Now update requests.yaml to use these variables:

requests:
  get-users:
    method: GET
    url: "{{.vars.baseUrl}}/users"
    expect:
      status: 200
      body:
        $: type array
        $.length: "> 0"

  create-user:
    method: POST
    url: "{{.vars.baseUrl}}/users"
    headers:
      Content-Type: application/json
    body:
      name: "{{.vars.userName}}"
      email: "{{.vars.userEmail}}"
      phone: "123-456-7890"
    expect:
      status: 201
      body:
        $.id: exists
        $.name: "{{.vars.userName}}"
        $.email: "{{.vars.userEmail}}"

Using variables:

  • {{.vars.baseUrl}} - Access variables with Go template syntax
  • Variables are grouped by profile (default, local)
  • Switch profiles with --profile flag

Run with default profile:

quadrastack

Or switch to local profile:

quadrastack --profile local

Step 6: Run Specific Tests

You can run individual requests instead of all tests:

# Run only get-users
quadrastack --request get-users

# Run multiple specific requests
quadrastack --request get-users --request create-user

Step 7: Get Detailed Output

For more information, enable verbose mode:

quadrastack --verbose

This shows:

  • Full request details (URL, headers, body)
  • Complete response data
  • Detailed assertion results
  • Timing information

Complete Example

Your final project structure:

my-first-api-test/
├── requests.yaml
└── vars.yaml

requests.yaml:

requests:
  get-users:
    method: GET
    url: "{{.vars.baseUrl}}/users"
    expect:
      status: 200
      body:
        $: type array
        $.length: "> 0"
        $[0].id: exists
        $[0].name: !empty
        $[0].email: matches "^[\\w.]+@[\\w.]+"

  create-user:
    method: POST
    url: "{{.vars.baseUrl}}/users"
    headers:
      Content-Type: application/json
    body:
      name: "{{.vars.userName}}"
      email: "{{.vars.userEmail}}"
      phone: "123-456-7890"
    expect:
      status: 201
      body:
        $.id: exists
        $.name: "{{.vars.userName}}"
        $.email: "{{.vars.userEmail}}"

vars.yaml:

vars:
  default:
    baseUrl: "https://jsonplaceholder.typicode.com"
    userName: "Jane Doe"
    userEmail: "jane.doe@example.com"

  local:
    baseUrl: "http://localhost:3000"
    userName: "Test User"
    userEmail: "test@localhost"

What You Learned

  • How to write GET and POST requests
  • Using the expect block for assertions
  • JSONPath syntax for validating response bodies
  • Compact DSL operators (exists, !empty, matches, >)
  • Variables and profiles for different environments
  • Running specific tests with --request
  • Getting detailed output with --verbose

Next Steps

Common Issues

"No YAML files found"

Make sure you're in the directory containing your YAML files, or use:

quadrastack --playbook-dir /path/to/yamls

Assertion Failed

Check your JSONPath syntax and expected values. Use --verbose to see the actual response:

quadrastack --verbose

Connection Errors

Verify the API is accessible:

curl https://jsonplaceholder.typicode.com/users

Tips

  1. Start Simple - Begin with basic requests, add assertions gradually
  2. Test Incrementally - Add one assertion at a time and verify it works
  3. Use Real APIs - Practice with public APIs like JSONPlaceholder, httpbin.org
  4. Copy and Modify - Use these examples as templates for your own tests
  5. Read Error Messages - The CLI provides detailed error messages to help debug

Congratulations! You've completed your first API test with Quadrastack. You now have the foundation to test any REST API.

Your First API Test - Quadrastack Docs