菜单
Use when setting up, running, or debugging integration tests against real Apple Contacts. Also use when unit tests pass but behavior seems wrong, when adding new AppleScript operations, or when you need to understand why mocked tests are insufficient for this project.
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
基于 SOC 职业分类
| name | integration-testing |
| description | Use when setting up, running, or debugging integration tests against real Apple Contacts. Also use when unit tests pass but behavior seems wrong, when adding new AppleScript operations, or when you need to understand why mocked tests are insufficient for this project. |
Unit tests mock _run_applescript() and test Python logic only. They CANNOT catch:
name, id, size selector collisions)The OmniFocus project's story: A variable naming typo went undetected by 400+ unit tests because they all mocked the AppleScript boundary. Only integration tests against the real app caught it. This lesson applies equally to Apple Contacts.
| Tier | Speed | What it catches | When to run |
|---|---|---|---|
| Unit (mocked) | ~1s, 99 tests | Python logic, parsing, validation | Every change |
| Integration (real) | ~30s | AppleScript bugs, Contacts.app quirks | New AppleScript code |
| E2E (full MCP) | ~30s | Tool registration, parameter passing | New/modified tools |
# Set test account (default: "Gmail")
export CONTACTS_TEST_GROUP="Gmail"
# Run integration tests
make test-integration
# Integration tests are opt-in
pytest tests/integration/ --run-integration -v
# Or via Makefile
make test-integration
import pytest
from apple_contacts_mcp.contacts_connector import AppleContactsConnector
# Skip unless explicitly enabled
pytestmark = pytest.mark.skipif(
"not config.getoption('--run-integration')",
reason="Integration tests disabled by default."
)
class TestMailIntegration:
@pytest.fixture
def connector(self) -> AppleContactsConnector:
return AppleContactsConnector()
@pytest.fixture
def test_account(self) -> str:
import os
return os.getenv("CONTACTS_TEST_GROUP", "Gmail")
def test_list_mailboxes(self, connector, test_account):
"""Verify we can list mailboxes from a real account."""
result = connector.list_mailboxes(test_account)
assert isinstance(result, list)
assert len(result) > 0
# INBOX should always exist
assert any("INBOX" in mb for mb in result)
@pytest.mark.skip(reason="Sends real email - enable manually")
def test_send_email(self, connector):
"""Test sending real email - enable manually only."""
...
# Destructive operations (send, delete, move) should be:
# 1. Skipped by default
# 2. Require explicit --run-integration flag
# 3. Require CONTACTS_TEST_GROUP environment variable
# 4. Target a specific test account, never "all accounts"
@pytest.fixture
def test_account(self) -> str:
"""Configurable test account - never hardcode."""
import os
return os.getenv("CONTACTS_TEST_GROUP", "Gmail")
# If test creates data (mailbox, flag), clean up in fixture teardown
@pytest.fixture
def test_mailbox(self, connector, test_account):
name = f"MCP-Test-{uuid.uuid4()}"
connector.create_mailbox(test_account, name)
yield name
try:
# Cleanup - don't fail if already deleted
connector.delete_mailbox(test_account, name)
except Exception:
pass
If you wrote or modified AppleScript in contacts_connector.py, integration tests must cover that operation before merge.
This is not optional. This is not "nice to have." Unit tests with mocked _run_applescript() give false confidence about AppleScript correctness.
CONTACTS_TEST_GROUP matches an actual configured account name in Contacts.appAppleContactsConnector(timeout=120)Use BEFORE adding any new tool, parameter, or endpoint to the Apple Contacts MCP server. Also use when considering API changes, evaluating feature requests, or when tempted to create a specialized operation. Contains the decision tree that prevents tool sprawl and the anti-pattern catalog.
Use BEFORE writing any code that touches Contacts.app data. Covers the Contacts.framework / PyObjC primary surface, the AppleScript fallback path for note + modification-date access, the TCC authorization flow, and the gotchas that aren't obvious from Apple's docs (entitlement-gated keys, raw label tokens, vCard 3.0-only export). Read together with `docs/research/contacts-api-gap-analysis.md` for the empirical basis.
Use when designing list/search/batch operations or chasing a slow tool. Establishes the empirical baselines from Phase 0 plus the patterns that hold for Contacts.framework specifically — most importantly the absence of subprocess overhead that makes mail-style perf advice misleading.
Use when the user wants to release a new version. Orchestrates the full release workflow including milestone check, version bump, changelog generation, validation, tagging, and PR creation. Also use when discussing release planning or version management.