clubber/openspec/changes/add-pytest-tests/proposal.md

Add Pytest Tests Proposal

Why

The project currently has no automated tests despite having pytest and pytest-asyncio configured in pyproject.toml. This creates several risks:

• Regression risk: Changes to existing features (member CRUD operations, GraphQL resolvers, MCP tools, validation logic) may break functionality without detection
• Confidence: Developers and AI assistants lack confidence when refactoring or adding features
• Documentation gap: Tests serve as executable documentation of expected behavior
• Quality assurance: No automated verification of business rules (validation, sorting, error handling)

Testing is critical for:

1. Member CRUD operations (create, read, update, delete)
2. GraphQL API (queries, mutations, introspection)
3. MCP server tools (6 tools connecting to GraphQL API)
4. Validation logic (email, phone, firstName)
5. Database operations (async SQLAlchemy patterns)

What

Implement comprehensive pytest test suite covering existing features:

Test Infrastructure

• Create tests/ directory with proper structure (unit, integration, e2e, mcp)
• Configure pytest fixtures for database setup (in-memory SQLite)
• Configure async test support (pytest-asyncio already in dependencies)
• Add conftest.py with shared fixtures

Test Coverage

1. Unit Tests (tests/unit/)

   • Validation logic (email, phone, firstName)
   • Utility functions

2. Integration Tests (tests/integration/)

   • Database operations with Member model
   • GraphQL resolvers (Query, Mutation)
   • Error handling (MemberNotFoundError, ValidationError)

3. E2E Tests (tests/e2e/)

   • Complete GraphQL query flows
   • Complete GraphQL mutation flows
   • GraphQL introspection queries

4. MCP Tests (tests/mcp/)

   • MCP server tool definitions
   • MCP tool execution (list_members, get_member, create_member, update_member)
   • General GraphQL tools (get_graphql_schema, execute_graphql_query)

Documentation

• Update README.md with testing instructions
• Add "Running Tests" section
• Add "Test Coverage" section
• Document test organization and conventions

Impact

Breaking Changes

None - purely additive.

New Dependencies

None - pytest and pytest-asyncio already in dev dependencies.

Migration

No migration needed.

Alternatives Considered

1. unittest instead of pytest

   • Rejected: pytest is already configured and provides better async support, fixtures, and test discovery

2. Test only critical paths

   • Rejected: Comprehensive testing provides better confidence and documentation

3. Skip MCP tests

   • Rejected: MCP server is a core component and needs testing

Success Criteria

1. Test suite runs with uv run pytest
2. All existing features have test coverage
3. Tests are organized logically (unit, integration, e2e, mcp)
4. Tests use proper fixtures for database setup
5. README.md documents how to run tests
6. No changes to production code (except minor fixes if bugs are found)

Related Changes

None - this is the first testing implementation.

Open Questions

None - the implementation is straightforward.