conftest.py

Overview

conftest.py is a pytest configuration and fixture definition file used within the InfiniFlow testing suite. Its primary purpose is to set up reusable test fixtures, configure test execution parameters, and provide helper utilities for testing the InfiniFlow RAG (Retrieval-Augmented Generation) flow system.

This file facilitates testing by:

• Managing test level selection (smoke/core/full) via CLI options.

• Providing authentication fixtures for HTTP API access.

• Creating, cleaning up, and managing datasets, documents, chat assistants, and sessions.

• Generating various test file types dynamically for upload and parsing tests.

• Synchronizing test workflows with document processing states.

It integrates closely with common test utilities and InfiniFlow’s API client libraries to orchestrate end-to-end test scenarios.

Detailed Explanation

Constants

• MARKER_EXPRESSIONS:
  A dictionary mapping test level keys (p1, p2, p3) to pytest marker expressions used to filter test execution.

  • "p1": Smoke tests

  • "p2": Core tests (default)

  • "p3": Full test suite

• HOST_ADDRESS:
  The base URL for the InfiniFlow HTTP API under test. Defaults to http://127.0.0.1:9380 if not set in environment variables.

pytest_addoption(parser: pytest.Parser) -> None

Adds a command-line option --level to pytest to select the test run level.

• Parameters:

  • parser: pytest parser object to add CLI options.

• Behavior:
  Defines the --level option with choices p1, p2, p3. Default is p2 (core tests).

• Usage Example:

  pytest --level=p1  # Run smoke tests only
  

pytest_configure(config: pytest.Config) -> None

Configures pytest based on CLI options, applying marker expressions to filter tests.

• Parameters:

  • config: pytest configuration object.

• Behavior:
  Reads the --level option, sets config.option.markexpr to the corresponding marker expression from MARKER_EXPRESSIONS, enabling selective test running.

• Side effect:
  Prints active test level if verbosity is enabled.

condition(_auth, _dataset_id) -> bool

A polling condition function decorated with @wait_for to check if document parsing has completed.

• Parameters:

  • _auth: Authentication object for API calls.

  • _dataset_id: ID of the dataset to check.

• Returns:

  • True if all documents’ run status is "DONE".

  • False otherwise.

• Usage:
  Used to wait (with timeout) for asynchronous document parsing to complete before proceeding with tests.

Fixtures

pytest fixtures declared with various scopes (function, class, session) to provide reusable test components.

get_http_api_auth(get_api_key_fixture) -> RAGFlowHttpApiAuth

• Scope: session

• Purpose: Provides an authenticated HTTP API client instance for use in tests.

• Parameters:

  • get_api_key_fixture: Fixture providing API key string.

• Returns:

  • Instance of RAGFlowHttpApiAuth initialized with the API key.

clear_datasets(request, get_http_api_auth)

• Scope: function

• Purpose: Cleans up all datasets after a test function completes.

• Implementation: Registers a finalizer to delete all datasets via API.

clear_chat_assistants(request, get_http_api_auth)

• Scope: function

• Purpose: Cleans up all chat assistants after each test function.

• Implementation: Registers a finalizer to delete all chat assistants.

clear_session_with_chat_assistants(request, get_http_api_auth, add_chat_assistants)

• Scope: function

• Purpose: Cleans up chat assistant sessions after test function execution.

• Implementation: Deletes sessions for all chat assistants added in the test.

generate_test_files(request, tmp_path) -> dict

• Scope: default (function)

• Purpose: Dynamically creates various test files in a temporary directory.

• Parameters:

  • request.param: Optional file type filter; creates only the matching file or all if empty.

  • tmp_path: Temporary directory pytest fixture.

• Returns:

  • A dictionary mapping file types to pathlib Path objects of generated files.

• Supported file types: docx, excel, ppt, image, pdf, txt, md, json, eml, html.

• Usage Example:

  @pytest.mark.parametrize('generate_test_files', ['pdf'], indirect=True)
  def test_pdf_processing(generate_test_files):
      pdf_file = generate_test_files['pdf']
      # Use pdf_file in test
  

ragflow_tmp_dir(request, tmp_path_factory) -> pathlib.Path

• Scope: class

• Purpose: Provides a unique temporary directory per test class.

• Returns:

  • Path object for class-specific temp directory.

add_dataset(request, get_http_api_auth) -> str

• Scope: class

• Purpose: Creates a dataset before tests and deletes all datasets after tests in the class.

• Returns:

  • Dataset ID string for use in tests.

add_dataset_func(request, get_http_api_auth) -> str

• Scope: function

• Purpose: Creates and cleans up a dataset per test function.

• Returns:

  • Dataset ID string.

add_document(get_http_api_auth, add_dataset, ragflow_tmp_dir) -> tuple[str, str]

• Scope: class

• Purpose: Uploads a document to a dataset and provides their IDs.

• Returns:

  • Tuple of (dataset_id, document_id).

add_chunks(get_http_api_auth, add_document) -> tuple[str, str, list[str]]

• Scope: class

• Purpose:

  • Parses documents, waits for completion, adds multiple content chunks to the document, and returns their IDs.

• Returns:

  • Tuple of (dataset_id, document_id, list_of_chunk_ids).

add_chat_assistants(request, get_http_api_auth, add_document) -> tuple[str, str, list[str]]

• Scope: class

• Purpose:

  • Parses documents, waits for completion, creates multiple chat assistants linked to the dataset, and returns their IDs.

• Returns:

  • Tuple of (dataset_id, document_id, list_of_chat_assistant_ids).

Important Implementation Details

• Test Level Selection:
  By adding the --level option and setting marker expressions dynamically, the test suite can selectively run subsets of tests (smoke/core/full) without changing code.

• Use of wait_for Decorator:
  The condition function is decorated with @wait_for(30, 1, "Document parsing timeout"), which polls the condition every second for up to 30 seconds, raising an error if the condition isn't met. This abstracts retry logic for asynchronous document processing.

• Resource Cleanup via Finalizers:
  Fixtures use request.addfinalizer() to ensure cleanup functions execute after tests, preventing side effects between tests and resource leaks.

• Dynamic File Generation:
  The generate_test_files fixture programmatically creates various file formats useful for testing document ingestion and parsing workflows.

• Handling of Asynchronous Operations:
  The add_chunks and add_chat_assistants fixtures parse documents then wait for the parsing to complete before proceeding, ensuring test consistency.

Interaction with Other System Components

• Imports from common:
  Functions like add_chunk, batch_create_datasets, bulk_upload_documents, create_chat_assistant, etc., are imported from a shared common module. These encapsulate HTTP API calls and business logic, enabling the fixtures here to orchestrate test scenarios easily.

• Authentication Module (libs.auth):
  The RAGFlowHttpApiAuth class is used to authenticate API calls. This fixture ensures all tests authenticate consistently.

• Utility Modules (libs.utils and libs.utils.file_utils):
  Utilities for waiting/polling and creating various file types are leveraged to support test setup and synchronization.

• Pytest Framework:
  This file leverages pytest’s fixture and configuration APIs extensively for clean, maintainable, and reusable test setups.

Visual Diagram

The following Mermaid flowchart describes the main functions and fixtures in conftest.py and their relationships, focusing on resource setup and cleanup workflows.

flowchart TD
    A[pytest CLI: --level option] --> B[pytest_addoption]
    B --> C[pytest_configure]
    C --> D{MARKER_EXPRESSIONS}
    D -->|Set markexpr| E[Filter tests by level]

    subgraph Authentication
        F[get_http_api_auth]
    end

    subgraph Dataset Management
        G[add_dataset]
        H[add_dataset_func]
        I[clear_datasets]
    end

    subgraph Document Management
        J[add_document]
        K[add_chunks]
        L[generate_test_files]
    end

    subgraph Chat Assistant Management
        M[add_chat_assistants]
        N[clear_chat_assistants]
        O[clear_session_with_chat_assistants]
    end

    subgraph Utilities
        P[condition (wait_for)]
    end

    F --> G
    F --> H
    G --> J
    J --> K
    J --> M
    K --> P
    M --> O

    I -.cleanup after test .-> G
    N -.cleanup after test .-> M
    O -.cleanup after test .-> M

    L --> J

    style A fill:#f9f,stroke:#333,stroke-width:2px
    style F fill:#bbf,stroke:#333,stroke-width:1px
    style G fill:#bbf,stroke:#333,stroke-width:1px
    style H fill:#bbf,stroke:#333,stroke-width:1px
    style I fill:#fbb,stroke:#333,stroke-width:1px,stroke-dasharray: 5 5
    style J fill:#bbf,stroke:#333,stroke-width:1px
    style K fill:#bbf,stroke:#333,stroke-width:1px
    style L fill:#bbf,stroke:#333,stroke-width:1px
    style M fill:#bbf,stroke:#333,stroke-width:1px
    style N fill:#fbb,stroke:#333,stroke-width:1px,stroke-dasharray: 5 5
    style O fill:#fbb,stroke:#333,stroke-width:1px,stroke-dasharray: 5 5
    style P fill:#ffb,stroke:#333,stroke-width:1px

Summary

conftest.py is a critical support file for the InfiniFlow test suite, enabling flexible test configuration and robust setup/teardown of datasets, documents, and chat assistants. It abstracts common testing concerns such as authentication, file generation, resource cleanup, and asynchronous state waiting into reusable fixtures and utilities, making test code simpler and more maintainable.

This file interacts tightly with shared common modules and utility libraries to execute realistic integration-style tests against the InfiniFlow HTTP API. Its design leverages pytest’s powerful fixture and configuration system to provide a scalable and configurable testing infrastructure.