docs: Add mock server tests playbook for declarative connectors (do not merge)

[devin-ai-integration[bot]]

What

Adds a comprehensive playbook documenting how to write mock server tests for Airbyte declarative (manifest-only) connectors using the airbyte-cdk's HttpMocker.

This playbook was created based on hands-on experience writing mock server tests for source-woocommerce and the reference gist.

How

Added a new markdown file at docs/contributing-to-airbyte/resources/mock-server-tests-playbook.md that covers:

1. Understanding the connector - How to analyze manifest.yaml to identify streams, pagination, and incremental sync patterns
2. Directory structure - Standard layout for unit_tests/ with pyproject.toml, conftest.py, and helper modules
3. Designing mock responses - How to match response format to field_path in manifest
4. Writing tests - Code examples for full refresh, pagination, incremental sync, and error handling
5. Running and debugging - Commands and common pitfalls with solutions
6. Quick reference checklist - Step-by-step summary

Review guide

1. docs/contributing-to-airbyte/resources/mock-server-tests-playbook.md - Single new documentation file

Key areas to verify:

• Code examples are syntactically correct and use current CDK APIs
• Troubleshooting table covers common issues accurately
• Directory structure matches monorepo conventions

User Impact

Provides connector developers with a standardized guide for writing mock server tests, reducing onboarding time and ensuring consistent test patterns across declarative connectors.

Can this PR be safely reverted and rolled back?

• [x] YES 💚

---

Link to Devin run: https://app.devin.ai/sessions/0d3f7f60a91249688d95a932a6419a3e Requested by: [email protected] (@sophiecuiy)

[devin-ai-integration[bot]]

Original prompt from [email protected]

@Devin Use this file to write mock server tests for [source-woocommerce].
Create representative test files to validate patterns for all streams.
Use the most commonly used streams.
<https://gist.github.com/ChristoGrab/bbf7171c508cc161be3cb4286d5a4daf>
Thread URL: https://airbytehq-team.slack.com/archives/D09QSGLP482/p1764699943740609

[devin-ai-integration[bot]]

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

• Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
• Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

• [ ] Disable automatic comment and CI monitoring

[github-actions[bot]]

👋 Greetings, Airbyte Team Member!

Here are some helpful tips and reminders for your convenience.

Helpful Resources

• Breaking Changes Guide - Breaking changes, migration guides, and upgrade deadlines
• Developing Connectors Locally
• Managing Connector Secrets
• On-Demand Live Tests
• On-Demand Regression Tests
• #connector-ci-issues
• #connector-publish-updates
• #connector-build-statuses

PR Slash Commands

Airbyte Maintainers (that's you!) can execute the following slash commands on your PR:

• /format-fix - Fixes most formatting issues.
• /bump-version - Bumps connector versions.
  • You can specify a custom changelog by passing changelog. Example: /bump-version changelog="My cool update"
  • Leaving the changelog arg blank will auto-populate the changelog from the PR title.
• /run-cat-tests - Runs legacy CAT tests (Connector Acceptance Tests)
• /run-live-tests - Runs live tests for the modified connector(s).
• /run-regression-tests - Runs regression tests for the modified connector(s).
• /build-connector-images - Builds and publishes a pre-release docker image for the modified connector(s).
• /publish-connectors-prerelease - Publishes pre-release connector builds (tagged as {version}-dev.{git-sha}) for all modified connectors in the PR.
• JVM connectors:
  • /update-connector-cdk-version connector=<CONNECTOR_NAME> - Updates the specified connector to the latest CDK version. Example: /update-connector-cdk-version connector=destination-bigquery
  • /bump-bulk-cdk-version bump=patch changelog='foo' - Bump the Bulk CDK's version. bump can be major/minor/patch.
• Python connectors:
  • /poe connector source-example lock - Run the Poe lock task on the source-example connector, committing the results back to the branch.
  • /poe source example lock - Alias for /poe connector source-example lock.
  • /poe source example use-cdk-branch my/branch - Pin the source-example CDK reference to the branch name specified.
  • /poe source example use-cdk-latest - Update the source-example CDK dependency to the latest available version.

📝 Edit this welcome message.

[github-actions[bot]]

Deploy preview for airbyte-docs ready!

✅ Preview https://airbyte-docs-fz2tsxees-airbyte-growth.vercel.app

Built with commit 715f4faf0be779383058869ee743c73cea7c63da. This pull request is being automatically deployed with vercel-action