Skip to main content

Python API Tests

Complete guide to the Python API test suite for hlquery.

Overview​

The Python API includes 31 comprehensive test scripts that verify all aspects of the hlquery API using the Python 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/python/tests
python3 test_get_document.py
python3 test_search.py
python3 test_filter_search.py

Running All Tests​

cd api/python/tests
python3 run_all_tests.py

Test Structure​

Common Test Pattern​

All Python tests follow this self-contained pattern:

#!/usr/bin/env python3
"""
Test Name

WHAT THIS TEST DOES:
1. Step-by-step description
2. What it tests
3. What it verifies

HOW TO RUN:
   python3 test_name.py
"""

import sys
import os

# Change to script directory
script_dir = os.path.dirname(os.path.abspath(__file__))
os.chdir(script_dir)
import time

# Add parent directory to path to allow importing lib
sys.path.insert(0, os.path.dirname(os.path.dirname(script_dir)))

from lib import 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.py​

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

test_get_collection.py​

Purpose: Retrieves collection details and schema information

What it tests:

  • Getting collection metadata
  • Retrieving collection fields
  • Handling non-existent collections

test_update_collection.py​

Purpose: Updates collection schemas

What it tests:

  • Modifying collection field definitions
  • Schema update validation

test_delete_collection.py​

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.py​

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_api().create(collection_name, schema)

# Insert document
doc = {
    'id': 'doc_123',
    'title': 'Test Document',
    'content': 'Content here',
    'tags': ['tag1', 'tag2']
}
add_resp = client.documents_api().add(collection_name, doc)

test_get_document.py​

Purpose: Retrieves individual documents by ID

What it tests:

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

test_update_document.py​

Purpose: Updates existing documents

What it tests:

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

test_delete_document.py​

Purpose: Deletes documents from collections

What it tests:

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

test_list_documents.py​

Purpose: Lists documents with pagination

What it tests:

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

Search Operations​

test_search.py​

Purpose: Basic search functionality

What it tests:

  • Text search across fields
  • Wildcard searches
  • Search with filters
  • Search with sorting
  • Search with pagination
  • 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.py​

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.py​

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.py​

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.search_api().multi_search(searches)

test_vector_search.py​

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)

test_pagination.py​

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.py​

Purpose: Faceted search results

What it tests:

  • Facet counts by field
  • Facet aggregation
  • Facet response structure

test_search_cols.py​

Purpose: Search within collections

What it tests:

  • Collection-specific search
  • Search result structure

Bulk Operations​

test_import_documents.py​

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_api().import_documents(collection_name, docs)

test_bulk_operations.py​

Purpose: Various bulk operations

What it tests:

  • Bulk document operations
  • Batch processing
  • Performance with large datasets

Advanced Features​

test_aliases.py​

Purpose: Collection alias management

What it tests:

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

test_auth.py​

Purpose: Authentication functionality

What it tests:

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

Example:

# Set bearer token
client.set_auth_token('your_token', 'bearer')

# Clear authentication
client.clear_auth()

test_data_types.py​

Purpose: Various data types

What it tests:

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

test_edge_cases.py​

Purpose: Edge cases and special scenarios

What it tests:

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

test_error_handling.py​

Purpose: Error handling

What it tests:

  • Invalid collection names
  • Invalid document IDs
  • Error response detection
  • Exception handling

test_export.py​

Purpose: Document export

What it tests:

  • Exporting collections
  • Export formats
  • Export endpoints (if available)

test_overrides.py​

Purpose: Search override management

What it tests:

  • Creating search overrides
  • Override endpoints (if available)
  • Override functionality

test_stopwords.py​

Purpose: Stopword management

What it tests:

  • Stopword configuration
  • Stopword endpoints (if available)
  • Stopword functionality

test_synonyms.py​

Purpose: Synonym management

What it tests:

  • Synonym configuration
  • Synonym endpoints (if available)
  • Synonym functionality

System Tests​

test_health.py​

Purpose: Health and status endpoints

What it tests:

  • /health endpoint
  • /status endpoint
  • /metrics endpoint
  • Response consistency

test_stats.py​

Purpose: Server statistics

What it tests:

  • Basic stats endpoint
  • Detailed statistics
  • Cache statistics
  • Connection statistics
  • RocksDB Statistics

test_list_all_cols.py​

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 = None
collections_resp = client.list_collections(0, 10)

if not collection_name:
    # Create test collection
    collection_name = 'test_' + str(int(time.time()))
    schema = {'fields': [...]}
    client.collections_api().create(collection_name, schema)
    created_test_collection = True

# Run tests...

# Cleanup
if created_test_collection:
    client.collections_api().delete(collection_name)

Pattern 2: Error Handling​

try:
    # Test code here
except Exception as e:
    print(f"\nFatal error: {str(e)}")
    import traceback
    traceback.print_exc()
    tests_failed += 1
    
    # Cleanup on error
    if created_test_collection and collection_name:
        try:
            client.collections_api().delete(collection_name)
        except:
            pass

Pattern 3: Response Validation​

response = client.get_document(collection_name, doc_id)

# Check status code
if response.get_status_code() == 200:
    body = response.get_body()
    
    # Validate structure
    if isinstance(body, dict) and 'id' in body:
        # 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.get_status_code() == 200, "Request successful"):
    tests_passed += 1
else:
    tests_failed += 1

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:

  1. Check if server is running: curl http://localhost:9200/health
  2. Verify BASE_URL in test file matches your server
  3. 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_api().delete('test_collection_name')

ModuleNotFoundError: No module named 'lib'​

Problem: Cannot import Client

Solution:

  • Tests automatically add the parent directory to sys.path
  • Ensure you're running from the test directory
  • Check that lib/ directory exists in api/python/

Best Practices​

When Writing New Tests​

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

Test Data Naming​

Use timestamp-based names to avoid conflicts:

collection_name = 'test_feature_' + str(int(time.time()))

Error Messages​

Provide helpful error messages:

if not collection_name:
    print("   No collections available - cannot run tests")
    print("   Create a collection first\n")

Contributing​

When adding new tests:

  1. Follow the existing test pattern
  2. Add comprehensive comments
  3. Include cleanup logic
  4. Test error cases
  5. Update this documentation

Support​

For issues with Python tests:

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