Teams — tests¶

Responsibilities¶

The Teams app test suite is responsible for verifying:

team listing behavior within an organization
team membership visibility rules
privileged vs non-privileged access
team creation, detail, update, deactivate, and reactivate rules
membership creation and lifecycle management
membership role updates
primary team membership behavior
team/org consistency validation
API integration for team and membership endpoints

It protects both: - business logic in services - route/view integration at the API layer

The test suite is especially important because Teams sits between: - org-level permissions - user-level workforce structure - planning/reporting features that depend on team grouping

Test structure¶

The Teams app uses a layered test strategy similar to the Accounts and Orgs apps.

Fixture layer¶

Provides: - organizations - users with org roles - teams - team memberships - authenticated API clients scoped to a current org

Service tests¶

Verify: - core business rules - visibility logic - team creation/update validation - team management permission checks - membership lifecycle behavior - membership management permission checks

API tests¶

Verify: - endpoint wiring - authentication and org-scoping - visibility and permission enforcement - serializer-backed payload structure - management endpoints for teams and memberships

Main test files¶

`tests/teams/conftest.py`¶

Defines reusable fixtures for the Teams app.

Typical fixtures include: - org - org_other - owner_user - admin_user - manager_user - engineer_user - viewer_user - other_org_user - team_a - team_b - team_other - owner_team_membership - manager_team_membership - engineer_team_membership - team_b_memberships - authenticated API clients per role

These fixtures create a realistic matrix of: - org roles - team memberships - current-org context

This is critical because most Teams behavior depends on both: - org membership - team membership

`tests/teams/test_team_services.py`¶

Tests service logic in teams.services.team.

Typical coverage: - resolving org role for a user - determining whether a user is privileged in the org - validating whether a user may manage teams - safe team lookup within an org - active-only team filtering - listing all teams in the org - listing the current user’s teams - creating teams - updating teams - deactivating teams - reactivating teams - duplicate name validation

This file protects the team-level service layer.

`tests/teams/test_membership_services.py`¶

Tests service logic in teams.services.membership.

Typical coverage: - retrieving memberships - active membership lookup - safe membership lookup in org scope - checking whether a user is in a team - listing team members - validating team visibility - validating whether a user may manage team memberships - resolving a user for membership creation - listing teammate options - listing visible membership pairs - listing visible membership rows - adding a user to a team - validating org membership prerequisite - updating team role - setting primary team membership - clearing primary team membership - deactivating membership - reactivating membership

This file protects the most important business rules in the Teams app.

`tests/teams/test_teams_api.py`¶

Tests API endpoints exposed by the Teams app.

Typical coverage: - auth requirement for listing all teams - privileged access to all teams - forbidden access for non-privileged users - current user team listing - team create endpoint - team detail endpoint - team update endpoint - team deactivate/reactivate endpoints - listing members of a team - visibility restrictions for team member listing - listing teammates across shared teams - compact membership pair endpoint - richer membership listing endpoint - membership create endpoint - membership role update endpoint - membership primary update endpoint - membership deactivate/reactivate endpoints - current-org header requirement

This file verifies end-to-end behavior from: - request - through views - through services - into serialized responses

Relationship overview¶

flowchart TD
    Tests["Teams tests"]

    Fixtures["conftest.py fixtures"]
    ServiceTests["Service tests"]
    APITests["API tests"]

    TeamServiceTests["test_team_services.py"]
    MembershipServiceTests["test_membership_services.py"]
    TeamsAPITests["test_teams_api.py"]

    Tests --> Fixtures
    Tests --> ServiceTests
    Tests --> APITests

    ServiceTests --> TeamServiceTests
    ServiceTests --> MembershipServiceTests
    APITests --> TeamsAPITests

¶

Test flow philosophy¶

Service-layer flow¶

sequenceDiagram
    participant Test as Service test
    participant Service as Team/Membership service
    participant Model as Team / TeamMembership / OrgMembership

    Test->>Service: call service function
    Service->>Model: query/update data
    Model-->>Service: result
    Service-->>Test: object / exception

API-layer flow¶


sequenceDiagram
    participant Test as API test
    participant View as Team view
    participant Service as Team/Membership service
    participant Serializer as Serializer
    participant Model as Models

    Test->>View: request with auth + org headers
    View->>Service: execute visibility/business logic
    Service->>Model: query/update data
    Model-->>Service: result
    Service-->>View: visible domain objects
    View->>Serializer: serialize response
    Serializer-->>View: payload
    View-->>Test: HTTP response

Key testing concerns¶

1. Current-org scoping¶

Most endpoints require: - HasCurrentOrg - X-ORG-ID - optionally X-ORG-SLUG

Tests must ensure current-org headers are present where required.

Without them: - endpoints may fail before team logic is executed

2. Org role and team membership are separate¶

A user’s team visibility depends on two different dimensions.

Org role¶

Used to determine privileged access: - owner - admin - manager

Team membership¶

Used to determine local visibility for non-privileged users.

Tests must account for both.

3. Primary team uniqueness¶

Only one is_primary=True team membership may exist per user.

This is protected by: - database constraint - service logic

Tests should assume that setting primary directly in raw fixtures can trigger DB errors unless done carefully.

4. Team/org consistency¶

A user may only belong to a team if they are a member of the same org.

This is one of the most important validation rules in the app and should remain covered by service tests.

5. Management permissions must stay centralized¶

Team and membership management must remain enforced through services.

Tests should continue protecting: - validate_team_management - validate_team_membership_management

This prevents future view-layer permission drift.

What the test suite protects most strongly¶

The Teams tests are especially important for preventing regressions in: - privileged team visibility - non-privileged restricted visibility - safe team lookup by org - safe membership lookup by org - uniqueness of team names per org - primary team switching - team and membership management permissions - membership add/remove/reactivate flows - cross-org membership invalidation - consistent team membership listing payloads

These are the areas most likely to cause: - permission leaks - confusing UI behavior - invalid staffing state

What is intentionally not over-tested¶

The suite currently avoids unnecessary duplication in a few places: - serializers are mostly tested through API tests rather than isolated heavily - views are tested for integration, not for every internal branch - model-level tests are limited because most business rules live in services - admin behavior is not tested at this stage

This keeps the suite focused and maintainable.

Known testing considerations¶

1. Route names must stay stable¶

The API tests depend on named routes such as: - teams-create - teams-detail - teams-update - teams-deactivate - teams-reactivate - teams-all-in-org - teams-my-in-org - teams-my-members-in-org - teams-members-by-team - teams-membership-create - teams-membership-pairs-in-org - teams-memberships-in-org - teams-membership-role-update - teams-membership-primary-update - teams-membership-deactivate - teams-membership-reactivate

Renaming them without updating tests will break the suite immediately.

2. Team role expansion should be handled carefully¶

If the TeamMembership.Role enum is expanded later, tests should continue to pass as long as: - existing roles like lead and member are preserved - service role validation is updated consistently - create/update endpoint payloads are adjusted alongside the enum

3. Some endpoint behavior is intentionally asymmetric¶

For example: - TeamMembersByTeamView returns 200 OK with an empty list when the team does not exist

This should be treated as intentional API behavior unless you decide to change the contract.