Your First Test

This guide walks you through creating and running your first test with NOIV, building on the Quick Start tutorial.

Understanding NOIV Test Structure

NOIV uses YAML files to define test suites. Here's the basic structure:

name: "My Test Suite"
base_url: "https://api.example.com"
headers:
  Content-Type: "application/json"
  Authorization: "Bearer ${API_TOKEN}"

tests:
  - name: "Test Description"
    url: "/endpoint"
    method: "GET"
    expected_status: 200
    validations:
      - type: "json_path"
        path: "$.data.id"
        expected: "12345"

Method 1: AI Generation (Recommended)

The easiest way to create your first test is using AI:

noiv generate natural "test a simple API that returns user information with proper status codes and JSON response validation"

This creates a file like generated_tests.yaml:

name: 'Tests: Test a simple API that returns user information'
tests:
  - name: "Get User Information - Success"
    url: "https://jsonplaceholder.typicode.com/users/1"
    method: "GET"
    expected_status: 200
    headers:
      Accept: "application/json"
    validations:
      - type: "status_code"
        expected: 200
      - type: "json_path"
        path: "$.name"
        expected: "exists"
      - type: "json_path"
        path: "$.email"
        expected: "contains:@"
  
  - name: "Get User Information - Not Found"
    url: "https://jsonplaceholder.typicode.com/users/999"
    method: "GET"
    expected_status: 404

Method 2: Interactive Builder

For more control, use the interactive builder:

noiv build

Follow the prompts:

Test name: My First API Test
Base URL: https://jsonplaceholder.typicode.com
HTTP method: GET
Endpoint path: /users/1
Expected status code: 200
Add custom headers? n
Add response validations? y
Validation type: json_path
JSON path: $.name
Expected value: Leanne Graham
Add another validation? n
Add another test? n

Method 3: Manual Creation

Create a YAML file manually:

# my_first_test.yaml
name: "My First Manual Test"
tests:
  - name: "Test JSONPlaceholder API"
    url: "https://jsonplaceholder.typicode.com/users/1"
    method: "GET"
    expected_status: 200
    validations:
      - type: "contains"
        value: "Leanne Graham"

Running Your Test

Execute your test with:

noiv test run my_first_test.yaml

Expected output:

Running test suite: My First Manual Test
Total tests: 1
Running tests... ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 100% 0:00:01

      Test Results Summary      
┏━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━┓
┃ Metric            ┃ Value    ┃
┡━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━┩
│ Total Tests       │ 1        │
│ Passed            │ 1        │
│ Failed            │ 0        │
│ Success Rate      │ 100.0%   │
│ Avg Response Time │ 245.3ms  │
└───────────────────┴──────────┘

Understanding Validation Types

NOIV supports several validation types:

Status Code Validation

validations:
  - type: "status_code"
    expected: 200

JSON Path Validation

validations:
  - type: "json_path"
    path: "$.user.email"
    expected: "user@example.com"

Contains Validation

validations:
  - type: "contains"
    value: "success"

Header Validation

validations:
  - type: "header"
    name: "Content-Type"
    expected: "application/json"

Adding Request Bodies

For POST/PUT requests, include request bodies:

tests:
  - name: "Create User"
    url: "https://jsonplaceholder.typicode.com/users"
    method: "POST"
    expected_status: 201
    headers:
      Content-Type: "application/json"
    body: |
      {
        "name": "John Doe",
        "email": "john@example.com",
        "username": "johndoe"
      }

Using Environment Variables

Keep sensitive data in environment variables:

# test.yaml
tests:
  - name: "Authenticated Request"
    url: "${BASE_URL}/protected-endpoint"
    headers:
      Authorization: "Bearer ${API_TOKEN}"

Set variables before running:

export BASE_URL="https://api.myapp.com"
export API_TOKEN="your-secret-token"
noiv test run test.yaml

Common Patterns

Testing Error Responses

tests:
  - name: "Invalid Request"
    url: "https://api.example.com/invalid-endpoint"
    method: "GET"
    expected_status: 404
    validations:
      - type: "contains"
        value: "Not Found"

Testing Authentication

tests:
  - name: "Unauthorized Access"
    url: "https://api.example.com/protected"
    method: "GET"
    expected_status: 401
  
  - name: "Authorized Access"
    url: "https://api.example.com/protected"
    method: "GET"
    headers:
      Authorization: "Bearer valid-token"
    expected_status: 200

Testing Data Creation Flow

tests:
  - name: "Create Resource"
    url: "https://api.example.com/resources"
    method: "POST"
    expected_status: 201
    body: |
      {
        "name": "Test Resource",
        "description": "Created by NOIV"
      }
    validations:
      - type: "json_path"
        path: "$.id"
        expected: "exists"
      - type: "header"
        name: "Location"
        expected: "contains:/resources/"

Viewing Test History

After running tests, view your history:

noiv test history

This shows all previous test runs with timestamps and results.

Next Steps

Now that you've created and run your first test:

1. Learn AI Generation - Master natural language test creation
2. Performance Testing - Add benchmarking to your tests
3. Import Tools - Convert existing Postman collections
4. Installation - Advanced test configuration options

Troubleshooting

Test Failures

If your test fails:

1. Check the URL is accessible
2. Verify expected status codes
3. Review validation criteria
4. Check network connectivity

YAML Syntax Errors

Common YAML issues:

• Indentation must be consistent (spaces, not tabs)
• Strings with special characters need quotes
• Lists require proper - formatting

Network Issues

For network-related failures:

• Verify internet connectivity
• Check if the API endpoint is accessible
• Consider firewall restrictions
• Try with noiv quick <url> first to test connectivity

Success!

You've successfully created and run your first NOIV test! This foundation will help you build more complex test suites as your API testing needs grow.