monke-testing-guide

Building Monke Tests for Source Connectors

Overview

Monke is Airweave's end-to-end testing framework for source connectors. It creates real test data in external systems, triggers syncs, and verifies data appears correctly in the search index.

This guide shows you how to build comprehensive tests that verify every entity type your connector supports.

---

Why Test Every Entity Type?

Important: Your Monke tests should create and verify all entity types defined in your source connector.

Many connector tests only verify top-level entities (e.g., tasks) but ignore nested entities (e.g., comments, files).

Impact:

• Comments might not sync properly → Silent failures in production
• File attachments might not be indexed → Missing searchable content
• Entity relationships might be broken → Poor search results
• Users can't search the full breadth of data they expect

Solution: Create test entities for every entity type your connector syncs, and verify each one appears in Qdrant.

Before Writing Monke Tests:

1. Open your source file: backend/airweave/platform/sources/{short_name}.py
2. List all entity types yielded in generate_entities():
   • Example: WorkspaceEntity, ProjectEntity, TaskEntity, CommentEntity, FileEntity
3. Your Monke tests should create at least one instance of each type
4. Verify each instance appears in Qdrant after sync

Validation:

• Count entity classes in entities/{short_name}.py
• Count entity types created in bongos/{short_name}.py::create_entities()
• These counts should match (excluding parent/workspace entities that don't get stored)

---

Core Components

Every Monke test requires four components:

1. Bongo implementation (monke/bongos/{short_name}.py)
2. Generation schemas (monke/generation/schemas/{short_name}.py)
3. Generation adapter (monke/generation/{short_name}.py)
4. Test configuration (monke/configs/{short_name}.yaml)

---

Part 1: Bongo Implementation

The Bongo is a class that creates, updates, and deletes test data via the external API.