How to Mock Fastio API Endpoints for Unit Testing

Mocking Fastio API endpoints lets you test agent workflows without an internet connection or spending API credits. By trading real API calls for simulated responses, you isolate the agent's logic. This confirms it handles Fastio data correctly, no matter the network state.

Agents interacting with Fastio workspaces need a steady stream of external inputs. These include uploaded files, metadata updates, search queries, and activity from the audit log. Waiting for real network requests during a test suite slows down development and adds flakiness. If your connection drops, DNS fails, or you hit a rate limit, the test fails. The failure has nothing to do with your agent's code.

According to the Google Testing Blog, unit tests with mocked APIs run up to 100x faster than end-to-end tests. This speed difference lets developers run thousands of tests in seconds. You get the immediate feedback you need when changing complex, multi-step agent workflows.

Mocking also protects your billing quota. The Fastio Business Trial provides multiple credits per month for production tasks. Running continuous integration (CI) tests against live endpoints on every pull request can drain that allowance fast.

For example, if you build an agent that reads many documents and asks Ripley (the built-in RAG agent) to answer user queries, your tests must simulate a successful upload, a follow-up file details read, and a cited answer. Mocks give you total control over these states. Your test suite becomes a reliable tool instead of a brittle bottleneck.

Helpful references: Fastio Workspaces, Fastio Collaboration, and Fastio AI.

Fastio operates as a workspace where agents and humans collaborate. Agents interact with Fastio through the Model Context Protocol (MCP). This interface connects the agent's logic with the platform. Agents use multiple MCP tools via Streamable HTTP or Server-Sent Events (SSE) to handle tasks like file uploads and semantic searches.

Testing these interactions means checking that your agent formats its MCP tool requests correctly, handles Authorization: Bearer {api_key} headers, and processes the returned session state. Because Fastio includes Ripley for RAG, an agent might upload a file and query its contents right away. To unit test this flow, mock the small-file upload (HTTP 201 with result, id, and new_file_id) and the later Ripley answer from the MCP ai tool (ask).

Another common pattern is an agent that creates an organization, adds a workspace, uploads files, and invites a human teammate. Testing this means mocking the documented routes: POST /current/org/create/, POST /current/org/{org_id}/create/workspace/, POST /current/upload/, and POST /current/workspace/{workspace_id}/members/{email_or_user_id}/.

You also need to mock URL import. When your agent pulls a file from a public URL into Fastio, the call is POST /current/web_upload/ with source_url, file_name, profile_id, profile_type (workspace or share), and folder_id. Mock that route, then mock GET /current/workspace/{workspace_id}/storage/{node_id}/details/ or GET /current/activity/poll/{entityId}?wait=95&lastactivity={timestamp} so the agent waits until the node is ready before it reads the file.

Testing Fastio integrations in Python works well with pytest and the responses library. This approach lets you intercept outgoing HTTP requests at the socket level and return predefined JSON payloads without hitting the network.

Here is an example of mocking a small-file upload. The real route is POST https://api.fast.io/current/upload/ (keep the trailing slash). The body is multipart/form-data with name, size, chunk (the bytes), action=create, instance_id (the workspace ID), and folder_id=root. A successful create returns HTTP 201: {"result":true,"id":"<upload_id>","new_file_id":"<node_id>"}. Your mock must use that URL and that response shape.

1. Install Required Testing Libraries Make sure you have your testing dependencies installed in your virtual environment. Run pip install pytest responses requests to set up your environment. If you are using asynchronous agents, you might also want to install pytest-asyncio and aioresponses.

2. Configure the Mock Response Use the @responses.activate decorator to capture requests targeting the Fastio API and provide a simulated success response. The request never leaves your local machine.

import requests
import responses
import pytest

@responses.activate
def test_agent_file_upload_success():
    upload_url = "https://api.fast.io/current/upload/"
    workspace_id = "1234567890123456789"

mock_response = {
        "result": True.
        "id": "9876543210987654321",
        "new_file_id": "1234567890987654321",
    }

responses.add(
        responses.POST,
        upload_url.
        json=mock_response.
        status=201,
        content_type="application/json",
    )

headers = {"Authorization": "Bearer test_agent_token_xyz"}
    files = {"chunk": ("financial_report_Q3.pdf", b"dummy PDF binary content")}
    form = {
        "name": "financial_report_Q3.pdf",
        "size": "1048576",
        "action": "create",
        "instance_id": workspace_id.
        "folder_id": "root",
    }
    response = requests.post(upload_url, headers=headers, files=files, data=form)

payload = response.json()
    assert response.status_code == 201
    assert payload["result"] is True
    assert payload["id"] == "9876543210987654321"
    assert payload["new_file_id"] == "1234567890987654321"

3. Verify the Workflow Locally Run pytest test_agent_upload.py to run the test. The responses library stops the request from reaching the Fastio server and returns your mock_response payload. This checks that your agent's data parsing and state management logic works without making a real network connection.

The most useful unit tests simulate failure. Real-world networks are unpredictable, and external APIs enforce strict rules. Your agents must handle these scenarios to avoid crashing, hanging, or losing data.

Testing Rate Limits (HTTP 429) Fastio enforces rate limits to maintain stability and fair usage. When an agent is rate limited, the API returns HTTP 429 with error code 1671. Back off until the time in the x-ve-limit-expires header. Configure your mock to return that status and header, then verify your agent waits and retries instead of spinning in a tight loop.

File Locks and Concurrency Fastio uses file locks so multi-agent writes stay orderly. Mock the real lock routes: POST /current/workspace/{workspace_id}/storage/{node_id}/lock/ to acquire, POST /current/workspace/{workspace_id}/storage/{node_id}/lock/heartbeat/ while the agent works, and DELETE /current/workspace/{workspace_id}/storage/{node_id}/lock/ to release. You can then check that Agent B waits, sends heartbeats if it holds the lock, and only writes after it acquires the lock.

Authentication Failures API keys can be rotated, and workspace permissions change. Mock HTTP responses that carry error code 1650 (Auth Invalid) or 1680 (Access Denied). Your tests should confirm the agent creates a new key with POST /current/user/auth/key/ when auth fails, or logs the permission failure and stops. It should not fail silently or enter an infinite retry loop.

Give Your AI Agents Persistent Storage

Start building and testing with Fastio's 50GB Business Trial and 19 consolidated tools. Built for mocking fast api endpoints unit testing workflows.

Start 14-Day Trial

For teams using the OpenClaw integration, testing works a bit differently. OpenClaw connects directly via the terminal command clawhub install dbalve/fast-io, providing multiple tools with no configuration for natural language file management.

When unit testing an OpenClaw implementation, you mock the tool execution layer instead of raw HTTP. Define mock outputs for the real MCP tools: upload, storage (list, search, details), find, and ai (ask). This lets you verify your OpenClaw agent interprets the mock data and generates the right natural language response.

Event-driven agent workflows watch workspace activity the same way. Mock GET /current/events/search/ for the audit log, or long-poll GET /current/activity/poll/{entityId}?wait=95&lastactivity={timestamp}. Coordination Rooms also emit room.message.created and room.participant.status_changed. Headless agents can wait on those through the MCP room tool (wait, messages, post).

Register those GET routes with responses (or mock the MCP event and room tools) so your agent sees a file land, reads new_file_id from the earlier upload, and asks Ripley for a cited summary without calling the live service.

Shifting from end-to-end integration testing to mock-heavy unit testing improves agent development. When a team relies on live API calls, a test suite for a multi-agent workflow might take multiple to multiple minutes to complete. This delay breaks developer flow, discourages testing, and slows down feature delivery.

By replacing external Fastio network calls with local mock responses, that same test suite often finishes in under multiple seconds. This performance gain enables reliable test-driven development (TDD) and efficient continuous integration (CI) pipelines.

Mocks guarantee deterministic results. In a live environment, an Intelligence Mode semantic search query might return different matches as LLM models evolve, embeddings are recalculated, or workspace indices are updated. A mock always returns the exact same semantic search result payload. This ensures your test assertions remain stable and reliable. This predictability builds a maintainable codebase for modern AI agents.