Orgs — tests¶

Responsibilities¶

The orgs test suite verifies that the app behaves correctly at the model, service, and API layers for organization, membership, and customer-link workflows.

It is responsible for testing:

organization lookup and current-org resolution
organization detail and branding updates
internal membership role and activation workflows
owner/admin permission boundaries
linked customer-org visibility
org-scoped API behavior

The suite also protects the refactored architecture by ensuring:

views stay thin
services own business rules
serializers validate payload shape
org role safety rules are enforced consistently

Test structure¶

The orgs app uses a layered test strategy.

API tests¶

These verify:

URL wiring and route names
authentication and current-org requirements
request/response shape
integration between views, serializers, and services
org-scoped permission behavior

Example: - test_orgs_api.py

Service tests¶

These verify:

organization lookup helpers
membership role logic
owner/admin constraints
deactivation/reactivation behavior
update workflows for org details and branding

Examples: - test_membership_services.py - test_organization_services.py

Fixtures¶

These provide:

internal orgs
customer orgs
internal users with different roles
customer users
org-scoped API clients
linked internal/customer org relationships

Example: - conftest.py

At this stage, dedicated model tests are not yet extensive because most critical behavior is currently exercised through services. If model-level logic grows later, model test files should be added.

Main test groups¶

Organization service tests¶

These tests verify the business logic in services.organization.

Typical coverage: - organization lookup by id - active organization lookup - current-org extraction from request - listing active orgs for a user - listing current org members - branding payload resolution - organization detail updates - organization branding updates

These tests protect the core organization helper behavior that views depend on.

Membership service tests¶

These tests verify the business logic in services.membership.

Typical coverage: - get membership / active membership - get user role in org - owner/admin detection - member-management permission checks - membership lookup scoped to an org - count active owners - role changes - self-management restrictions - admin vs owner boundaries - last-owner protection - membership deactivate/reactivate - create/update membership helper

These are the most important service tests because membership logic is security-sensitive.

Orgs API tests¶

These tests verify the public endpoints of the app.

Typical coverage: - my orgs requires authentication - current org detail requires org context - current org detail returns correct payload - current org update allowed for admin/owner - current org update forbidden for lower roles - current org branding read/update endpoints - current org member list endpoint - membership role update endpoint - membership deactivate/reactivate endpoints - customer-link listing - linked customer-org member listing - cross-org restrictions

These tests confirm that the API exposes the correct behavior on top of the service layer.

Current fixtures¶

Core org fixtures¶

Typical organization fixtures include: - org - org_other - customer_org - customer_org_other

These create realistic internal and customer organizations.

User fixtures¶

Typical user fixtures include: - owner_user - admin_user - manager_user - engineer_user - viewer_user - other_org_owner_user - customer_user

These give the test suite a realistic role matrix.

API client fixtures¶

Typical client fixtures include: - owner_api_client - admin_api_client - manager_api_client - engineer_api_client - viewer_api_client - other_org_owner_api_client - anon_api_client

These clients are pre-authenticated and, where needed, already scoped to an org via request headers.

Relationship fixtures¶

Typical relationship fixtures include: - linked_customer

This makes linked customer-org tests simple and reusable.

Layered testing strategy¶

The orgs suite intentionally separates concerns by layer.

API layer tests focus on¶

endpoint routing
authentication
current-org scoping
serializer integration
response status codes
one representative happy path per endpoint

Service layer tests focus on¶

permission rules
membership state transitions
owner/admin safety constraints
multi-step workflow logic
exception behavior

Fixture layer supports¶

realistic org role combinations
current-org request scoping
customer-link relationships
reusable setup across service and API tests

This keeps the suite maintainable while still protecting the critical authorization and tenancy behavior.

Relationship overview¶

flowchart TD
    Tests["Orgs tests"]

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

    OrgService["Organization service tests"]
    MembershipService["Membership service tests"]
    OrgAPI["Orgs API tests"]

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

    ServiceTests --> OrgService
    ServiceTests --> MembershipService
    APITests --> OrgAPI

¶

Test flow philosophy¶

API intigration flow¶

sequenceDiagram
    participant API as API tests
    participant View as Views
    participant Serializer as Serializers
    participant Service as Services
    participant Model as Models

    API->>View: call endpoint
    View->>Serializer: validate payload
    View->>Service: execute org/membership workflow
    Service->>Model: query/update state
    Model-->>Service: result
    Service-->>View: domain result
    View-->>API: response

service-layer flow¶

sequenceDiagram
    participant SvcTest as Service tests
    participant Service as Services
    participant Model as Models

    SvcTest->>Service: call function directly
    Service->>Model: query/update state
    Model-->>Service: result
    Service-->>SvcTest: object / exception

What the suite protects most strongly¶

The current orgs tests are especially important for preventing regressions in:

current-org resolution assumptions
role-based org member management
last-owner safety rules
admin vs owner permission boundaries
org detail and branding update flows
linked customer-org visibility
org-scoped query behavior

These are the parts of the app most likely to cause security or tenancy bugs if broken.

What is intentionally not over-tested¶

The suite avoids unnecessary duplication where another layer already covers the same behavior well.

Examples:

business branching is mainly tested in service tests
API tests do not repeat every membership state rule
serializers are exercised through API tests rather than isolated heavily
direct model tests are limited until model-level logic grows further

This keeps the suite lean and high-value.

Known testing considerations¶

1. Current-org headers matter¶

Many org endpoints require request-scoped org context, typically via headers like:

X-ORG-ID
X-ORG-SLUG

If those are missing, tests may fail before reaching view logic.

2. Unique membership constraints matter¶

Fixtures already create memberships for some users, so tests should usually mutate existing memberships rather than creating duplicate (user, org) rows.

3. Owner safety rules are easy to trip¶

Tests involving role changes or deactivation of owners should be explicit about whether there is more than one active owner.

Likely future additions¶

As the orgs app expands, likely test additions include:

customer-link write API tests
organization hierarchy/tree tests
ownership transfer tests
branding validation tests
customer-membership management tests
organization creation/update lifecycle tests
audit-history assertions if history usage becomes operationally important