REST API Testing - sebiboga/testlink-upgraded GitHub Wiki

TestLink REST API v3 - Testing & Documentation

Complete REST API v3 testing resources for TestLink v1.9.20.

Overview

This guide covers the TestLink REST API v3 with comprehensive documentation, Postman collection, and automated testing tools.

Includes:

  • Complete API endpoint documentation
  • Pre-configured Postman collection with all endpoints
  • Newman CLI tool for automated API testing
  • Custom HTML report template
  • Environment configuration for easy setup
  • Real-world examples and usage patterns

Quick Start

1. Import Postman Collection

  1. Open Postman
  2. Click "Import" button
  3. Select TestLink.postman_collection.json
  4. Import environment: environment.json
  5. Configure variables (API token, base URL)
  6. Execute requests

2. Use Newman for CLI Testing

Installation:

npm install -g newman newman-reporters-html

Run Tests:

newman run TestLink.postman_collection.json \
  --environment environment.json \
  --reporters cli,html

View Report:

open test-results.html

API Base URL

https://your-testlink-instance/api/rest/v3

Authentication

Two methods supported:

Bearer Token (Recommended)

Authorization: Bearer YOUR_API_TOKEN

Basic Auth

Authorization: Basic base64(username:password)

Core API Endpoints

Authentication

  • GET /whoami - Get current user
  • POST /login - Authenticate user
  • POST /logout - End session

Projects

  • GET /projects - List projects
  • POST /projects - Create project
  • GET /projects/{id} - Get project
  • PUT /projects/{id} - Update project
  • DELETE /projects/{id} - Delete project

Test Plans

  • GET /projects/{id}/plans - List plans
  • POST /plans - Create plan
  • GET /plans/{id} - Get plan
  • PUT /plans/{id} - Update plan
  • DELETE /plans/{id} - Delete plan

Test Cases

  • GET /projects/{id}/testcases - List test cases
  • POST /testcases - Create test case
  • GET /testcases/{id} - Get test case
  • PUT /testcases/{id} - Update test case
  • DELETE /testcases/{id} - Delete test case

Test Execution

  • POST /execution/create - Record execution
  • GET /execution/{id} - Get execution
  • GET /execution/history - Get history

Builds

  • GET /projects/{id}/builds - List builds
  • POST /builds - Create build
  • PUT /builds/{id} - Update build

Users

  • GET /users - List users
  • POST /users - Create user
  • GET /users/{id} - Get user

Keywords

  • GET /keywords - List keywords
  • POST /keywords - Create keyword

Custom Fields

  • GET /customfields - List fields
  • GET /customfields/{id} - Get field

API Response Format

Success Response

{
  "status": "success",
  "data": { ... },
  "message": "Operation successful",
  "code": 200
}

Error Response

{
  "status": "error",
  "message": "Error description",
  "code": 400
}

HTTP Status Codes

Code Meaning
200 OK
201 Created
400 Bad Request
401 Unauthorized
403 Forbidden
404 Not Found
500 Server Error

Common Use Cases

Create a Test Project

curl -X POST https://testlink/api/rest/v3/projects \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Project",
    "prefix": "MP"
  }'

Create Test Case with Steps

curl -X POST https://testlink/api/rest/v3/testcases \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Login Test",
    "project_id": 1,
    "suite_id": 1,
    "steps": [
      {
        "actions": "Enter username",
        "expected_results": "Field accepts input"
      },
      {
        "actions": "Click login",
        "expected_results": "User logged in"
      }
    ]
  }'

Record Test Execution

curl -X POST https://testlink/api/rest/v3/execution/create \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "testcase_id": 1,
    "plan_id": 1,
    "build_id": 1,
    "status": "passed",
    "notes": "Test passed"
  }'

Get Execution History

curl -X GET "https://testlink/api/rest/v3/execution/history?testcase_id=1&plan_id=1" \
  -H "Authorization: Bearer YOUR_TOKEN"

Using Postman Collection

Pre-configured Requests

The collection includes:

Authentication

  • Get current user (whoami)
  • Login
  • Logout

Projects (5 requests)

  • List projects
  • Get project
  • Create project
  • Update project
  • Delete project

Test Plans (5 requests)

  • List plans
  • Get plan
  • Create plan
  • Update plan
  • Delete plan

Test Cases (5 requests)

  • List test cases
  • Get test case
  • Create test case
  • Update test case
  • Delete test case

Execution (3 requests)

  • Record execution
  • Get execution
  • Get execution history

Builds (3 requests)

  • List builds
  • Create build
  • Update build

Users (3 requests)

  • List users
  • Get user
  • Create user

Keywords (2 requests)

  • List keywords
  • Create keyword

Custom Fields (2 requests)

  • List fields
  • Get field

Environment Variables

Configure these variables in Postman environment:

base_url: https://your-testlink/api/rest/v3
api_token: YOUR_API_TOKEN
username: admin
password: admin
project_id: 1
plan_id: 1
testcase_id: 1
build_id: 1

Newman CLI Testing

Features

  • Automated Testing - Run entire API test suite
  • CI/CD Integration - Easy integration with pipelines
  • HTML Reports - Professional test result reports
  • Request Validation - Assert responses
  • Performance Metrics - Track response times

Configuration File

newman.json:

{
  "collection": "TestLink.postman_collection.json",
  "environment": "environment.json",
  "reporters": ["cli", "html"],
  "reporterOptions": {
    "html": {
      "export": "test-results.html",
      "template": "newman-tpl.hbs"
    }
  }
}

Run Tests

# Run with configuration file
newman run newman.json

# Run specific folder
newman run TestLink.postman_collection.json \
  --folder "Projects"

# Run with custom environment
newman run TestLink.postman_collection.json \
  --environment production-env.json

# Generate detailed report
newman run TestLink.postman_collection.json \
  --environment environment.json \
  --reporters cli,html,json \
  --reporter-html-export ./reports/detailed.html

Report Template

Custom newman-tpl.hbs provides:

  • Summary statistics
  • Pass/fail counts
  • Request details
  • Response times
  • Error messages
  • Formatted output

Bash Script Example

#!/bin/bash

API_TOKEN="your_token"
BASE_URL="https://testlink/api/rest/v3"

# Create project
PROJECT=$(curl -s -X POST "$BASE_URL/projects" \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Test Project",
    "prefix": "TP"
  }')

PROJECT_ID=$(echo $PROJECT | jq -r '.data.id')
echo "Created project: $PROJECT_ID"

# Create test case
TESTCASE=$(curl -s -X POST "$BASE_URL/testcases" \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{
    \"name\": \"Login Test\",
    \"project_id\": $PROJECT_ID,
    \"suite_id\": 1
  }")

TESTCASE_ID=$(echo $TESTCASE | jq -r '.data.id')
echo "Created test case: $TESTCASE_ID"

# Record execution
curl -s -X POST "$BASE_URL/execution/create" \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{
    \"testcase_id\": $TESTCASE_ID,
    \"plan_id\": 1,
    \"build_id\": 1,
    \"status\": \"passed\"
  }" | jq .

Python Example

import requests
import json

API_TOKEN = "your_token"
BASE_URL = "https://testlink/api/rest/v3"

headers = {
    "Authorization": f"Bearer {API_TOKEN}",
    "Content-Type": "application/json"
}

# List projects
response = requests.get(f"{BASE_URL}/projects", headers=headers)
projects = response.json()["data"]

print(f"Found {len(projects)} projects")

# Create project
data = {
    "name": "Python Test Project",
    "prefix": "PTP"
}
response = requests.post(f"{BASE_URL}/projects", 
                         headers=headers, json=data)
project = response.json()["data"]
print(f"Created project: {project['id']}")

# Record execution
exec_data = {
    "testcase_id": 1,
    "plan_id": 1,
    "build_id": 1,
    "status": "passed",
    "notes": "API test passed"
}
response = requests.post(f"{BASE_URL}/execution/create",
                         headers=headers, json=exec_data)
print(response.json())

Error Handling

Common Errors

Error Cause Solution
401 Unauthorized Invalid token Verify token
403 Forbidden No permissions Check user role
404 Not Found Invalid ID Verify resource exists
400 Bad Request Invalid data Check JSON format

Best Practices

  1. Use Pagination - Limit result sets
  2. Cache Results - Reduce API calls
  3. Handle Errors - Proper error handling
  4. Log Requests - Track API usage
  5. Secure Tokens - Protect credentials
  6. Use HTTPS - Encrypt communication
  7. Batch Operations - Combine requests
  8. Monitor Performance - Track response times

Security

  • Store tokens securely (environment variables)
  • Use HTTPS only
  • Rotate tokens regularly
  • Don't commit tokens to version control
  • Limit token scope and expiration
  • Monitor for suspicious activity

Performance Tips

  • Use pagination (limit/offset)
  • Cache static data
  • Filter results server-side
  • Minimize number of calls
  • Use bulk operations
  • Monitor response times

Support & Resources

  • GitHub Issues - Report bugs
  • GitHub Discussions - Ask questions
  • Wiki - Check documentation
  • API-Documentation - Full API reference
  • Developer-Guide - Development guide

Files Included

  • README.md - Comprehensive API documentation
  • TestLink.postman_collection.json - Postman collection
  • environment.json - Postman environment
  • newman.json - Newman configuration
  • newman-tpl.hbs - Report template

Version: TestLink 1.9.20
API Version: REST v3
Last Updated: August 2026