test_list_documents.py

Overview

This file contains comprehensive automated tests for the list_documnets API endpoint/functionality within the InfiniFlow system. The primary purpose is to verify the correctness, robustness, and expected behavior of the document listing feature under various scenarios, including authorization, pagination, filtering, sorting, and concurrency.

The tests are implemented using pytest, a popular Python testing framework, and cover both positive (successful cases) and negative (error handling) scenarios. The file is organized into two main test classes focusing on:

• Authorization: Verifying responses when API authentication is missing or invalid.

• Documents List: Testing the document listing API with various query parameters and edge cases.

These tests help ensure the integrity and reliability of the document listing API, which is critical for users to access datasets and documents securely and efficiently.

Classes and Methods

TestAuthorization

This class contains tests related to API authentication and authorization when calling list_documnets.

test_invalid_auth(self, auth, expected_code, expected_message)

• Purpose: Test the behavior of the list documents API when the authorization token is missing or invalid.

• Parameters:

  • auth: An authentication object or None.

  • expected_code: Expected numeric response code from the API.

  • expected_message: Expected error or status message.

• Behavior: Calls list_documnets with the provided auth and checks that the response code and message match expectations.

• Example Usage:

auth = RAGFlowHttpApiAuth(INVALID_API_TOKEN)
res = list_documnets(auth, "dataset_id")
assert res["code"] == 109
assert res["message"] == "Authentication error: API key is invalid!"

TestDocumentsList

This class contains detailed tests for various aspects of the document listing API, including pagination, filtering, sorting, concurrency, and parameter validation.

test_default(self, get_http_api_auth, add_documents)

• Purpose: Basic test to verify that listing documents returns the expected number of documents and success code.

• Parameters:

  • get_http_api_auth: Fixture providing valid authentication.

  • add_documents: Fixture that adds sample documents and returns (dataset_id, document_ids).

• Behavior: Calls list_documnets for the dataset and asserts 5 documents are returned successfully.

test_invalid_dataset_id(self, get_http_api_auth, dataset_id, expected_code, expected_message)

• Purpose: Tests invalid or unauthorized dataset IDs.

• Parameters:

  • dataset_id: Dataset identifier, including empty or invalid cases.

  • expected_code: Expected API response code.

  • expected_message: Expected error message.

• Behavior: Verifies correct error handling when dataset ID is invalid or unauthorized.

test_page(self, get_http_api_auth, add_documents, params, expected_code, expected_page_size, expected_message)

• Purpose: Tests pagination parameter page handling.

• Parameters:

  • params: Dictionary with pagination parameters, e.g., {"page": 2, "page_size": 2}.

  • expected_code: Expected response code.

  • expected_page_size: Expected number of documents returned.

  • expected_message: Expected error message (if any).

• Behavior: Checks correct document counts and error handling for valid and invalid page inputs.

test_page_size(self, get_http_api_auth, add_documents, params, expected_code, expected_page_size, expected_message)

• Purpose: Tests pagination parameter page_size handling.

• Parameters: Similar to test_page, but focusing on page size values.

• Behavior: Validates that page size limits and invalid inputs are handled correctly.

test_orderby(self, get_http_api_auth, add_documents, params, expected_code, assertions, expected_message)

• Purpose: Tests sorting order of documents based on fields like create_time or update_time.

• Parameters:

  • params: Sorting parameters, e.g., {"orderby": "create_time"}.

  • assertions: Callable that checks if results are sorted as expected.

  • expected_code: Expected response code.

  • expected_message: Expected error message.

• Behavior: Verifies sorting functionality and proper error handling for unknown sort keys.

test_desc(self, get_http_api_auth, add_documents, params, expected_code, assertions, expected_message)

• Purpose: Tests the sorting direction (desc) parameter.

• Parameters: Similar to test_orderby.

• Behavior: Ensures that descending/ascending ordering is respected and invalid values are handled gracefully.

test_keywords(self, get_http_api_auth, add_documents, params, expected_num)

• Purpose: Tests filtering documents by keyword search.

• Parameters:

  • params: Dictionary with keyword filters, e.g., {"keywords": "ragflow_test_upload"}.

  • expected_num: Expected number of documents matching the keyword.

• Behavior: Checks that keyword filtering returns the correct subset of documents.

test_name(self, get_http_api_auth, add_documents, params, expected_code, expected_num, expected_message)

• Purpose: Tests filtering documents by exact document name.

• Parameters:

  • params: Dictionary with name parameter.

  • expected_code: Expected response code.

  • expected_num: Expected number of documents found.

  • expected_message: Expected error message.

• Behavior: Validates name-based filtering and ownership authorization.

test_id(self, get_http_api_auth, add_documents, document_id, expected_code, expected_num, expected_message)

• Purpose: Tests filtering documents by document ID.

• Parameters:

  • document_id: Document ID or callable that returns an ID.

  • Other parameters same as above.

• Behavior: Verifies ID filtering and handles missing/unknown IDs correctly.

test_name_and_id(self, get_http_api_auth, add_documents, document_id, name, expected_code, expected_num, expected_message)

• Purpose: Tests combined filtering by both document ID and name.

• Parameters:

  • document_id: Document ID or callable.

  • name: Document name.

  • Other parameters same as above.

• Behavior: Ensures combined filters work correctly and unauthorized access is denied.

test_concurrent_list(self, get_http_api_auth, add_documents)

• Purpose: Stress test for concurrent access to the document listing API.

• Behavior: Uses ThreadPoolExecutor to concurrently invoke list_documnets 100 times and asserts all succeed.

test_invalid_params(self, get_http_api_auth, add_documents)

• Purpose: Tests API behavior when unexpected parameters are passed.

• Behavior: Confirms that unknown parameters do not break the API and default behavior is maintained.

Important Implementation Details

• The tests use pytest markers such as @pytest.mark.p1, @pytest.mark.p2, and @pytest.mark.p3 to indicate priority or category.

• Some tests are parameterized to cover multiple input cases efficiently.

• Skipped tests (pytest.mark.skip) are annotated with issue references, indicating known bugs or pending fixes.

• The list_documnets function is imported from the common module and is the central API under test.

• Authentication is simulated using RAGFlowHttpApiAuth from the libs.auth module.

• Utility function is_sorted from libs.utils is used to verify sorting order assertions.

• ThreadPoolExecutor is utilized for concurrent testing to simulate high-load scenarios.

Interaction with Other Parts of the System

• Authentication: The tests depend on RAGFlowHttpApiAuth to simulate API authentication tokens.

• Common Module: The list_documnets function is the API client that interacts with the backend document listing service.

• Fixtures: The tests use pytest fixtures such as get_http_api_auth and add_documents to set up authenticated sessions and seed test data.

• Utilities: Sorting verification relies on is_sorted utility.

• Concurrent Execution: The use of ThreadPoolExecutor tests the thread safety and performance under concurrent requests.

This test suite ensures the document listing API integrates correctly with authentication, dataset management, and supports client-side parameters properly.

Usage Examples

Example of a test that checks invalid authentication:

def test_invalid_auth():
    auth = RAGFlowHttpApiAuth(INVALID_API_TOKEN)
    res = list_documnets(auth, "dataset_id")
    assert res["code"] == 109
    assert res["message"] == "Authentication error: API key is invalid!"

Example of testing pagination:

def test_page(get_http_api_auth, add_documents):
    dataset_id, _ = add_documents
    params = {"page": 2, "page_size": 2}
    res = list_documnets(get_http_api_auth, dataset_id, params=params)
    assert res["code"] == 0
    assert len(res["data"]["docs"]) == 2

Mermaid Diagram - Class Structure

classDiagram
    class TestAuthorization {
        +test_invalid_auth(auth, expected_code, expected_message)
    }
    class TestDocumentsList {
        +test_default(get_http_api_auth, add_documents)
        +test_invalid_dataset_id(get_http_api_auth, dataset_id, expected_code, expected_message)
        +test_page(get_http_api_auth, add_documents, params, expected_code, expected_page_size, expected_message)
        +test_page_size(get_http_api_auth, add_documents, params, expected_code, expected_page_size, expected_message)
        +test_orderby(get_http_api_auth, add_documents, params, expected_code, assertions, expected_message)
        +test_desc(get_http_api_auth, add_documents, params, expected_code, assertions, expected_message)
        +test_keywords(get_http_api_auth, add_documents, params, expected_num)
        +test_name(get_http_api_auth, add_documents, params, expected_code, expected_num, expected_message)
        +test_id(get_http_api_auth, add_documents, document_id, expected_code, expected_num, expected_message)
        +test_name_and_id(get_http_api_auth, add_documents, document_id, name, expected_code, expected_num, expected_message)
        +test_concurrent_list(get_http_api_auth, add_documents)
        +test_invalid_params(get_http_api_auth, add_documents)
    }

Summary

test_list_documents.py is a critical test suite focusing on validating the document listing API endpoint in the InfiniFlow project. It covers:

• Authorization and authentication validation.

• Pagination (page and page size), including edge cases and errors.

• Sorting and ordering of documents.

• Filtering by keywords, document name, and document ID.

• Concurrent access robustness.

• Handling of invalid or unexpected parameters.

By systematically exercising these features, this file ensures the document listing service is secure, reliable, and user-friendly, preventing regressions and aiding maintainability of the InfiniFlow backend API.