PHP API Tests

Complete guide to the PHP API test suite for hlquery.

Overview

The PHP API includes 31 comprehensive test scripts that verify all aspects of the hlquery API using the PHP client library. Each test is self-contained, creates its own test data when needed, and cleans up afterward.

Quick Start

Running Individual Tests

cd api/php/tests
php test_get_document.php
php test_search.php
php test_filter_search.php

Running All Tests

cd api/php/tests
for test in test_*.php; do
    echo "Running $test..."
    php "$test"
    echo ""
done

Test Structure

Common Test Pattern

All PHP tests follow this self-contained pattern:

#!/usr/bin/env php
<?php
/**
 * Test Name
 *
 * WHAT THIS TEST DOES:
 * 1. Step-by-step description
 * 2. What it tests
 * 3. What it verifies
 *
 * HOW TO RUN:
 *   php test_name.php
 */

require_once __DIR__ . '/../lib/autoload.php';

use Hlquery\Client;

$BASE_URL = 'http://localhost:9200';

// Helper functions (assert_test, display_response)
// Main test function
// Cleanup logic

Key Features

Self-Contained: Tests create their own data if needed
Automatic Cleanup: Test data is removed after tests
Clear Output: Uses indicators and detailed status
Error Handling: Proper error handling with cleanup
Exit Codes: Returns 0 on success, 1 on failure

Available Tests

Core CRUD Operations

test_create_collection.php

Purpose: Tests creating collections with schemas

What it tests:

Creating a collection with field definitions
Verifying collection exists after creation
Collection schema validation

Key Concepts:

Schema defines what fields documents can have
Field types: string, int32, float, bool, string[], float[]
Collections must have unique names

Example Output:

----------------------------------------------------------------==============================
TEST: Create Collection (PHP API)
----------------------------------------------------------------------

1. Creating collection with schema
   Collection name: test_create_1234567890
POST /collections (create)
   Status: 201
   ✓ Collection created successfully
   Collection creation returns 200/201

2. Verifying collection exists
   ✓ Verified collection exists
   Collection response is array/object
   Collection has name or fields

3. Cleaning up test collection
   ✓ Cleaned up collection: test_create_1234567890

----------------------------------------------------------------==============================
Test Summary: 3 passed, 0 failed
----------------------------------------------------------------==============================

test_get_collection.php

Purpose: Retrieves collection details and schema information

What it tests:

Getting collection metadata
Retrieving collection fields
Handling non-existent collections

test_update_collection.php

Purpose: Updates collection schemas

What it tests:

Modifying collection field definitions
Schema update validation

test_delete_collection.php

Purpose: Deletes collections and verifies deletion

What it tests:

Collection deletion
Verification that collection no longer exists
Error handling for already-deleted collections

Document Operations

test_docs_insert.php

Purpose: Tests inserting documents into collections

What it tests:

Creating collections with schemas
Inserting documents with various field types
Verifying documents were inserted correctly

Key Code Pattern:

// Create collection
$schema = [
    'fields' => [
        ['name' => 'title', 'type' => 'string'],
        ['name' => 'content', 'type' => 'string'],
        ['name' => 'tags', 'type' => 'string[]']
    ]
];
$create_resp = $client->collections()->create($collection_name, $schema);

// Insert document
$doc = [
    'id' => 'doc_123',
    'title' => 'Test Document',
    'content' => 'Content here',
    'tags' => ['tag1', 'tag2']
];
$add_resp = $client->documents()->add($collection_name, $doc);

test_get_document.php

Purpose: Retrieves individual documents by ID

What it tests:

Getting documents by ID
Document structure validation
Error handling for non-existent documents

Key Features:

Automatically finds or creates test data
Tests both successful retrieval and error cases
Verifies document content matches expectations

test_update_document.php

Purpose: Updates existing documents

What it tests:

Updating document fields
Verifying updates were applied
Partial updates (updating only some fields)

test_delete_document.php

Purpose: Deletes documents from collections

What it tests:

Document deletion
Verification that document no longer exists
Cleanup of test data

test_list_documents.php

Purpose: Lists documents with pagination

What it tests:

Listing all documents in a collection
Pagination (offset/limit)
Response structure validation

Search Operations

test_search.php

Purpose: Basic search functionality

What it tests:

Text search across fields
Wildcard searches
Search result structure

Key Concepts:

q parameter: search query string
query_by: fields to search in (comma-separated)
limit: maximum number of results

test_filter_search.php

Purpose: Search with filter conditions

What it tests:

Simple filters (category:test)
Multiple filters with AND (category:test && status:active)
Numeric filters (price:>15)
OR filters (category:test || category:premium)
Filters combined with sorting

Filter Syntax Examples:

// Simple filter
'filter_by' => 'category:test'

// AND filter
'filter_by' => 'category:test && status:active'

// OR filter
'filter_by' => 'category:test || category:premium'

// Numeric comparison
'filter_by' => 'price:>15'
'filter_by' => 'price:<=100'

test_sort_search.php

Purpose: Search with sorting

What it tests:

Ascending sort (sort_by => 'price:asc')
Descending sort (sort_by => 'price:desc')
Multiple field sorting

test_multi_search.php

Purpose: Multi-collection search

What it tests:

Searching across multiple collections simultaneously
Handling multiple search results
Result aggregation

Example:

$searches = [
    ['collection' => 'products', 'q' => 'laptop', 'query_by' => 'title'],
    ['collection' => 'articles', 'q' => 'laptop', 'query_by' => 'content']
];
$results = $client->searchApi()->multiSearch($searches);

test_vector_search.php

Purpose: Vector similarity search

What it tests:

Creating collections with vector fields (float[])
Inserting documents with embedding vectors
Performing vector similarity searches
Vector query parameters (threshold, normalize)

Key Concepts:

Vector fields store arrays of floating-point numbers
Used for semantic similarity search
Requires documents with matching vector dimensions

test_pagination.php

Purpose: Pagination in searches and listings

What it tests:

Offset/limit pagination
Multiple pages of results
Pagination in both search and list operations

test_facets.php

Purpose: Faceted search results

What it tests:

Facet counts by field
Facet aggregation
Facet response structure

Bulk Operations

test_import_documents.php

Purpose: Bulk document import

What it tests:

Importing multiple documents at once
Bulk import response handling
Verifying all documents were imported

Example:

$docs = [
    ['id' => 'doc1', 'title' => 'Doc 1'],
    ['id' => 'doc2', 'title' => 'Doc 2'],
    ['id' => 'doc3', 'title' => 'Doc 3']
];
$result = $client->documents()->import($collection_name, $docs);

test_bulk_operations.php

Purpose: Various bulk operations

What it tests:

Bulk document operations
Batch processing
Performance with large datasets

Advanced Features

test_aliases.php

Purpose: Collection alias management

What it tests:

Alias creation and management
Using aliases in queries
Alias endpoints (if available)

test_auth.php

Purpose: Authentication functionality

What it tests:

Health check without authentication
Bearer token authentication
API key authentication
Token validation

Example:

// Set bearer token
$client->setAuthToken('your_token', 'bearer');

// Clear authentication
$client->clearAuth();

test_data_types.php

Purpose: Various data types

What it tests:

String fields
Integer fields (int32)
Float fields
Boolean fields
Array fields (string[], float[])

test_edge_cases.php

Purpose: Edge cases and special scenarios

What it tests:

Empty queries
Very long collection names
Non-existent resources
Special characters

test_error_handling.php

Purpose: Error handling

What it tests:

Invalid collection names
Invalid document IDs
Error response detection
Exception handling

test_export.php

Purpose: Document export

What it tests:

Exporting collections
Export formats
Export endpoints (if available)

test_overrides.php

Purpose: Search override management

What it tests:

Creating search overrides
Override endpoints (if available)
Override functionality

test_stopwords.php

Purpose: Stopword management

What it tests:

Stopword configuration
Stopword endpoints (if available)
Stopword functionality

test_synonyms.php

Purpose: Synonym management

What it tests:

Synonym configuration
Synonym endpoints (if available)
Synonym functionality

System Tests

test_health.php

Purpose: Health and status endpoints

What it tests:

/health endpoint
/status endpoint
/metrics endpoint
Response consistency

test_stats.php

Purpose: Server statistics

What it tests:

Basic stats endpoint
Detailed statistics
Cache statistics
Connection statistics
RocksDB Statistics

test_list_all_cols.php

Purpose: List all collections

What it tests:

Listing collections with pagination
Collection metadata
Collection counts

Understanding Test Output

Success Indicators

Green checkmark: Test assertion passed
Red X: Test assertion failed
Chart icon: API response display
✓ Checkmark: Operation completed successfully
Warning: Non-critical issue or information

Test Summary

Each test ends with a summary:

----------------------------------------------------------------==============================
Test Summary: 5 passed, 0 failed
----------------------------------------------------------------==============================

Exit code 0: All tests passed
Exit code 1: One or more tests failed

Common Patterns

Pattern 1: Self-Contained Test Data

// Find or create test collection
$collection_name = null;
$collections_resp = $client->listCollections(0, 10);

if (!$collection_name) {
    // Create test collection
    $collection_name = 'test_' . time();
    $schema = ['fields' => [...]];
    $client->collections()->create($collection_name, $schema);
    $created_test_collection = true;
}

// Run tests...

// Cleanup
if ($created_test_collection) {
    $client->collections()->delete($collection_name);
}

Pattern 2: Error Handling

try {
    // Test code here
} catch (Exception $e) {
    echo "\nFatal error: " . $e->getMessage() . "\n";
    $tests_failed++;
    
    // Cleanup on error
    if ($created_test_collection && $collection_name) {
        try {
            $client->collections()->delete($collection_name);
        } catch (Exception $e2) {
            // Ignore cleanup errors
        }
    }
}

Pattern 3: Response Validation

$response = $client->getDocument($collection_name, $doc_id);

// Check status code
if ($response->getStatusCode() === 200) {
    $body = $response->getBody();
    
    // Validate structure
    if (is_array($body) && isset($body['id'])) {
        // Test passed
    }
}

Helper Functions

All tests include these helper functions:

`assert_test($condition, $message)`

Asserts a condition and prints pass/fail.

if (assert_test($response->getStatusCode() === 200, "Request successful")) {
    $tests_passed++;
} else {
    $tests_failed++;
}

`display_response($test_name, $response, $show_body)`

Displays API response in readable format.

display_response("GET /collections/my_col", $response);
// Shows:
// GET /collections/my_col
//    Status: 200
//    Response: { ... formatted JSON ... }

Troubleshooting

Test Fails with Connection Error

Problem: Cannot connect to server

Solution:

Check if server is running: curl http://localhost:9200/health
Verify $BASE_URL in test file matches your server
Check firewall/network settings

Test Creates Data But Doesn't Clean Up

Problem: Test data remains after test

Solution:

Tests should clean up automatically

If cleanup fails, manually delete test collections:

$client->collections()->delete('test_collection_name');

"Test not yet implemented" Message

Problem: Test file shows placeholder message

Solution:

All PHP tests are now fully implemented
If you see this, the file may be outdated
Check git status for uncommitted changes

Best Practices

When Writing New Tests

Use self-contained pattern: Create test data if needed
Always cleanup: Delete test collections/documents
Handle errors: Use try-catch blocks with cleanup
Clear output: Use helper functions for consistent formatting
Exit codes: Return 0 on success, 1 on failure
Add comments: Explain what the test does and why

Test Data Naming

Use timestamp-based names to avoid conflicts:

$collection_name = 'test_feature_' . time();

Error Messages

Provide helpful error messages:

if (!$collection_name) {
    echo "   No collections available - cannot run tests\n";
    echo "   Create a collection first\n";
}

PHP Client Documentation - Complete PHP client API reference
Testing Guide - General testing documentation
Testing Examples - Detailed test examples
API Overview - API endpoint documentation

Contributing

When adding new tests:

Follow the existing test pattern
Add comprehensive comments
Include cleanup logic
Test error cases
Update this documentation

Support

For issues with PHP tests:

Check server is running and accessible
Verify PHP dependencies are installed
Review test output for specific error messages
Check server logs for detailed errors

Overview​

Quick Start​

Running Individual Tests​

Running All Tests​

Test Structure​

Common Test Pattern​

Key Features​

Available Tests​

Core CRUD Operations​

test_create_collection.php​

test_get_collection.php​

test_update_collection.php​

test_delete_collection.php​

Document Operations​

test_docs_insert.php​

test_get_document.php​

test_update_document.php​

test_delete_document.php​

test_list_documents.php​

Search Operations​

test_search.php​

test_filter_search.php​

test_sort_search.php​

test_multi_search.php​

test_vector_search.php​

test_pagination.php​

test_facets.php​

Bulk Operations​

test_import_documents.php​

test_bulk_operations.php​

Advanced Features​

test_aliases.php​

test_auth.php​

test_data_types.php​

test_edge_cases.php​

test_error_handling.php​

test_export.php​

test_overrides.php​

test_stopwords.php​

test_synonyms.php​

System Tests​

test_health.php​

test_stats.php​

test_list_all_cols.php​

Understanding Test Output​

Success Indicators​

Test Summary​

Common Patterns​

Pattern 1: Self-Contained Test Data​

Pattern 2: Error Handling​

Pattern 3: Response Validation​

Helper Functions​

assert_test($condition, $message)​

display_response($test_name, $response, $show_body)​

Troubleshooting​

Test Fails with Connection Error​

Test Creates Data But Doesn't Clean Up​

"Test not yet implemented" Message​

Best Practices​

When Writing New Tests​

Test Data Naming​

Error Messages​

Related Documentation​

Contributing​

Support​

Overview

Quick Start

Running Individual Tests

Running All Tests

Test Structure

Common Test Pattern

Key Features

Available Tests

Core CRUD Operations

test_create_collection.php

test_get_collection.php

test_update_collection.php

test_delete_collection.php

Document Operations

test_docs_insert.php

test_get_document.php

test_update_document.php

test_delete_document.php

test_list_documents.php

Search Operations

test_search.php

test_filter_search.php

test_sort_search.php

test_multi_search.php

test_vector_search.php

test_pagination.php

test_facets.php

Bulk Operations

test_import_documents.php

test_bulk_operations.php

Advanced Features

test_aliases.php

test_auth.php

test_data_types.php

test_edge_cases.php

test_error_handling.php

test_export.php

test_overrides.php

test_stopwords.php

test_synonyms.php

System Tests

test_health.php

test_stats.php

test_list_all_cols.php

Understanding Test Output

Success Indicators

Test Summary

Common Patterns

Pattern 1: Self-Contained Test Data

Pattern 2: Error Handling

Pattern 3: Response Validation

Helper Functions

`assert_test($condition, $message)`

`display_response($test_name, $response, $show_body)`

Troubleshooting

Test Fails with Connection Error

Test Creates Data But Doesn't Clean Up

"Test not yet implemented" Message

Best Practices

When Writing New Tests

Test Data Naming

Error Messages

Related Documentation

Contributing

Support