unchained/mission-control
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

refactor: update module docstrings for clarity and consistency

Browse Source
This commit is contained in:
Abhimanyu Saharan
2026-02-09 15:49:50 +05:30
parent 78bb08d4a3
commit 7ca1899d9f
99 changed files with 2345 additions and 855 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
backend/tests/__init__.py Normal file
View File

@@ -0,0 +1 @@
"""Backend test package."""

3
backend/tests/conftest.py
View File

@@ -1,3 +1,6 @@
# ruff: noqa: INP001
"""Pytest configuration shared across backend tests."""
import sys
from pathlib import Path

29
backend/tests/test_board_groups_delete.py
View File

@@ -1,24 +1,30 @@
# ruff: noqa: INP001, S101
"""Regression test for board-group delete ordering."""
from __future__ import annotations
from dataclasses import dataclass, field
from types import SimpleNamespace
from typing import Any
from typing import TYPE_CHECKING, cast
from uuid import uuid4
import pytest
from app.api import board_groups
if TYPE_CHECKING:
from sqlmodel.ext.asyncio.session import AsyncSession
@dataclass
class _FakeSession:
executed: list[Any] = field(default_factory=list)
executed: list[object] = field(default_factory=list)
committed: int = 0
async def exec(self, statement: Any) -> None:
async def exec(self, statement: object) -> None:
self.executed.append(statement)
async def execute(self, statement: Any) -> None:
async def execute(self, statement: object) -> None:
self.executed.append(statement)
async def commit(self) -> None:
@@ -29,17 +35,26 @@ class _FakeSession:
async def test_delete_board_group_cleans_group_memory_first(
monkeypatch: pytest.MonkeyPatch,
) -> None:
"""Delete should remove boards, memory, then the board-group record."""
group_id = uuid4()
async def _fake_require_group_access(*_args: Any, **_kwargs: Any) -> None:
async def _fake_require_group_access(*_args: object, **_kwargs: object) -> None:
return None
monkeypatch.setattr(board_groups, "_require_group_access", _fake_require_group_access)
monkeypatch.setattr(
board_groups,
"_require_group_access",
_fake_require_group_access,
)
session = _FakeSession()
ctx = SimpleNamespace(member=object())
await board_groups.delete_board_group(group_id=group_id, session=session, ctx=ctx)
await board_groups.delete_board_group(
group_id=group_id,
session=cast("AsyncSession", session),
ctx=ctx,
)
statement_tables = [statement.table.name for statement in session.executed]
assert statement_tables == ["boards", "board_group_memory", "board_groups"]

42
backend/tests/test_board_schema.py
View File

@@ -1,3 +1,6 @@
# ruff: noqa: INP001
"""Schema validation tests for board and onboarding goal requirements."""
from uuid import uuid4
import pytest
@@ -6,8 +9,12 @@ from app.schemas.board_onboarding import BoardOnboardingConfirm
from app.schemas.boards import BoardCreate
def test_goal_board_requires_objective_and_metrics_when_confirmed():
with pytest.raises(ValueError):
def test_goal_board_requires_objective_and_metrics_when_confirmed() -> None:
"""Confirmed goal boards should require objective and success metrics."""
with pytest.raises(
ValueError,
match="Confirmed goal boards require objective and success_metrics",
):
BoardCreate(
name="Goal Board",
slug="goal",
@@ -27,22 +34,39 @@ def test_goal_board_requires_objective_and_metrics_when_confirmed():
)
def test_goal_board_allows_missing_objective_before_confirmation():
def test_goal_board_allows_missing_objective_before_confirmation() -> None:
"""Draft goal boards may omit objective/success_metrics before confirmation."""
BoardCreate(name="Draft", slug="draft", gateway_id=uuid4(), board_type="goal")
def test_general_board_allows_missing_objective():
BoardCreate(name="General", slug="general", gateway_id=uuid4(), board_type="general")
def test_general_board_allows_missing_objective() -> None:
"""General boards should allow missing goal-specific fields."""
BoardCreate(
name="General",
slug="general",
gateway_id=uuid4(),
board_type="general",
)
def test_onboarding_confirm_requires_goal_fields():
with pytest.raises(ValueError):
def test_onboarding_confirm_requires_goal_fields() -> None:
"""Onboarding confirm should enforce goal fields for goal board types."""
with pytest.raises(
ValueError,
match="Confirmed goal boards require objective and success_metrics",
):
BoardOnboardingConfirm(board_type="goal")
with pytest.raises(ValueError):
with pytest.raises(
ValueError,
match="Confirmed goal boards require objective and success_metrics",
):
BoardOnboardingConfirm(board_type="goal", objective="Ship onboarding")
with pytest.raises(ValueError):
with pytest.raises(
ValueError,
match="Confirmed goal boards require objective and success_metrics",
):
BoardOnboardingConfirm(board_type="goal", success_metrics={"emails": 3})
BoardOnboardingConfirm(

30
backend/tests/test_boards_delete.py
View File

@@ -1,7 +1,10 @@
# ruff: noqa: INP001, S101
"""Regression tests for board deletion cleanup behavior."""
from __future__ import annotations
from dataclasses import dataclass, field
from typing import Any
from typing import TYPE_CHECKING, cast
from uuid import uuid4
import pytest
@@ -9,27 +12,32 @@ import pytest
from app.api import boards
from app.models.boards import Board
if TYPE_CHECKING:
from sqlmodel.ext.asyncio.session import AsyncSession
_NO_EXEC_RESULTS_ERROR = "No more exec_results left for session.exec"
@dataclass
class _FakeSession:
exec_results: list[Any]
executed: list[Any] = field(default_factory=list)
deleted: list[Any] = field(default_factory=list)
exec_results: list[object]
executed: list[object] = field(default_factory=list)
deleted: list[object] = field(default_factory=list)
committed: int = 0
async def exec(self, statement: Any) -> Any:
async def exec(self, statement: object) -> object | None:
is_dml = statement.__class__.__name__ in {"Delete", "Update", "Insert"}
if is_dml:
self.executed.append(statement)
return None
if not self.exec_results:
raise AssertionError("No more exec_results left for session.exec")
raise AssertionError(_NO_EXEC_RESULTS_ERROR)
return self.exec_results.pop(0)
async def execute(self, statement: Any) -> None:
async def execute(self, statement: object) -> None:
self.executed.append(statement)
async def delete(self, value: Any) -> None:
async def delete(self, value: object) -> None:
self.deleted.append(value)
async def commit(self) -> None:
@@ -38,6 +46,7 @@ class _FakeSession:
@pytest.mark.asyncio
async def test_delete_board_cleans_org_board_access_rows() -> None:
"""Deleting a board should clear org-board access rows before commit."""
session = _FakeSession(exec_results=[[], []])
board = Board(
id=uuid4(),
@@ -47,7 +56,10 @@ async def test_delete_board_cleans_org_board_access_rows() -> None:
gateway_id=None,
)
await boards.delete_board(session=session, board=board)
await boards.delete_board(
session=cast("AsyncSession", session),
board=board,
)
deleted_table_names = [statement.table.name for statement in session.executed]
assert "organization_board_access" in deleted_table_names

26
backend/tests/test_organizations_delete_api.py
View File

@@ -1,8 +1,11 @@
# ruff: noqa: INP001, S101
"""Tests for organization deletion API behavior and authorization."""
from __future__ import annotations
from dataclasses import dataclass, field
from types import SimpleNamespace
from typing import Any
from typing import TYPE_CHECKING, cast
from uuid import uuid4
import pytest
@@ -10,16 +13,19 @@ from fastapi import HTTPException, status
from app.api import organizations
if TYPE_CHECKING:
from sqlmodel.ext.asyncio.session import AsyncSession
@dataclass
class _FakeSession:
executed: list[Any] = field(default_factory=list)
executed: list[object] = field(default_factory=list)
committed: int = 0
async def exec(self, statement: Any) -> None:
async def exec(self, statement: object) -> None:
self.executed.append(statement)
async def execute(self, statement: Any) -> None:
async def execute(self, statement: object) -> None:
self.executed.append(statement)
async def commit(self) -> None:
@@ -28,6 +34,7 @@ class _FakeSession:
@pytest.mark.asyncio
async def test_delete_my_org_cleans_dependents_before_organization_delete() -> None:
"""Delete flow should remove dependent rows before the organization row."""
session = _FakeSession()
org_id = uuid4()
ctx = SimpleNamespace(
@@ -35,7 +42,10 @@ async def test_delete_my_org_cleans_dependents_before_organization_delete() -> N
member=SimpleNamespace(role="owner"),
)
await organizations.delete_my_org(session=session, ctx=ctx)
await organizations.delete_my_org(
session=cast("AsyncSession", session),
ctx=ctx,
)
executed_tables = [statement.table.name for statement in session.executed]
assert executed_tables == [
@@ -66,6 +76,7 @@ async def test_delete_my_org_cleans_dependents_before_organization_delete() -> N
@pytest.mark.asyncio
async def test_delete_my_org_requires_owner_role() -> None:
"""Delete flow should reject non-owner members with HTTP 403."""
session = _FakeSession()
ctx = SimpleNamespace(
organization=SimpleNamespace(id=uuid4()),
@@ -73,7 +84,10 @@ async def test_delete_my_org_requires_owner_role() -> None:
)
with pytest.raises(HTTPException) as exc_info:
await organizations.delete_my_org(session=session, ctx=ctx)
await organizations.delete_my_org(
session=cast("AsyncSession", session),
ctx=ctx,
)
assert exc_info.value.status_code == status.HTTP_403_FORBIDDEN
assert session.executed == []

74
backend/tests/test_organizations_service.py
View File

@@ -1,3 +1,5 @@
# ruff: noqa
from __future__ import annotations
from dataclasses import dataclass, field
@@ -14,7 +16,10 @@ from app.models.organization_invites import OrganizationInvite
from app.models.organization_members import OrganizationMember
from app.models.organizations import Organization
from app.models.users import User
from app.schemas.organizations import OrganizationBoardAccessSpec, OrganizationMemberAccessUpdate
from app.schemas.organizations import (
OrganizationBoardAccessSpec,
OrganizationMemberAccessUpdate,
)
from app.services import organizations
@@ -82,7 +87,10 @@ class _FakeSession:
def test_normalize_invited_email_strips_and_lowercases() -> None:
assert organizations.normalize_invited_email(" Foo@Example.com ") == "foo@example.com"
assert (
organizations.normalize_invited_email(" Foo@Example.com ")
== "foo@example.com"
)
@pytest.mark.parametrize(
@@ -104,13 +112,13 @@ def test_role_rank_unknown_role_falls_back_to_member_rank() -> None:
def test_is_org_admin_owner_admin_member() -> None:
assert organizations.is_org_admin(
OrganizationMember(organization_id=uuid4(), user_id=uuid4(), role="owner")
OrganizationMember(organization_id=uuid4(), user_id=uuid4(), role="owner"),
)
assert organizations.is_org_admin(
OrganizationMember(organization_id=uuid4(), user_id=uuid4(), role="admin")
OrganizationMember(organization_id=uuid4(), user_id=uuid4(), role="admin"),
)
assert not organizations.is_org_admin(
OrganizationMember(organization_id=uuid4(), user_id=uuid4(), role="member")
OrganizationMember(organization_id=uuid4(), user_id=uuid4(), role="member"),
)
@@ -119,7 +127,9 @@ async def test_ensure_member_for_user_returns_existing_membership(
monkeypatch: pytest.MonkeyPatch,
) -> None:
user = User(clerk_user_id="u1")
existing = OrganizationMember(organization_id=uuid4(), user_id=user.id, role="member")
existing = OrganizationMember(
organization_id=uuid4(), user_id=user.id, role="member",
)
async def _fake_get_active(_session: Any, _user: User) -> OrganizationMember:
return existing
@@ -150,10 +160,12 @@ async def test_ensure_member_for_user_accepts_pending_invite(
async def _fake_find(_session: Any, _email: str) -> OrganizationInvite:
return invite
accepted = OrganizationMember(organization_id=org_id, user_id=user.id, role="member")
accepted = OrganizationMember(
organization_id=org_id, user_id=user.id, role="member",
)
async def _fake_accept(
_session: Any, _invite: OrganizationInvite, _user: User
_session: Any, _invite: OrganizationInvite, _user: User,
) -> OrganizationMember:
assert _invite is invite
assert _user is user
@@ -203,7 +215,9 @@ async def test_has_board_access_denies_cross_org() -> None:
member = OrganizationMember(organization_id=uuid4(), user_id=uuid4(), role="member")
board = Board(id=uuid4(), organization_id=uuid4(), name="b", slug="b")
assert (
await organizations.has_board_access(session, member=member, board=board, write=False)
await organizations.has_board_access(
session, member=member, board=board, write=False,
)
is False
)
@@ -211,7 +225,9 @@ async def test_has_board_access_denies_cross_org() -> None:
@pytest.mark.asyncio
async def test_has_board_access_uses_org_board_access_row_read_and_write() -> None:
org_id = uuid4()
member = OrganizationMember(id=uuid4(), organization_id=org_id, user_id=uuid4(), role="member")
member = OrganizationMember(
id=uuid4(), organization_id=org_id, user_id=uuid4(), role="member",
)
board = Board(id=uuid4(), organization_id=org_id, name="b", slug="b")
access = OrganizationBoardAccess(
@@ -222,7 +238,9 @@ async def test_has_board_access_uses_org_board_access_row_read_and_write() -> No
)
session = _FakeSession(exec_results=[_FakeExecResult(first_value=access)])
assert (
await organizations.has_board_access(session, member=member, board=board, write=False)
await organizations.has_board_access(
session, member=member, board=board, write=False,
)
is True
)
@@ -234,7 +252,9 @@ async def test_has_board_access_uses_org_board_access_row_read_and_write() -> No
)
session2 = _FakeSession(exec_results=[_FakeExecResult(first_value=access2)])
assert (
await organizations.has_board_access(session2, member=member, board=board, write=False)
await organizations.has_board_access(
session2, member=member, board=board, write=False,
)
is True
)
@@ -246,13 +266,17 @@ async def test_has_board_access_uses_org_board_access_row_read_and_write() -> No
)
session3 = _FakeSession(exec_results=[_FakeExecResult(first_value=access3)])
assert (
await organizations.has_board_access(session3, member=member, board=board, write=True)
await organizations.has_board_access(
session3, member=member, board=board, write=True,
)
is False
)
@pytest.mark.asyncio
async def test_require_board_access_raises_when_no_member(monkeypatch: pytest.MonkeyPatch) -> None:
async def test_require_board_access_raises_when_no_member(
monkeypatch: pytest.MonkeyPatch,
) -> None:
user = User(clerk_user_id="u1")
board = Board(id=uuid4(), organization_id=uuid4(), name="b", slug="b")
@@ -263,7 +287,9 @@ async def test_require_board_access_raises_when_no_member(monkeypatch: pytest.Mo
session = _FakeSession(exec_results=[])
with pytest.raises(HTTPException) as exc:
await organizations.require_board_access(session, user=user, board=board, write=False)
await organizations.require_board_access(
session, user=user, board=board, write=False,
)
assert exc.value.status_code == 403
@@ -271,18 +297,26 @@ async def test_require_board_access_raises_when_no_member(monkeypatch: pytest.Mo
async def test_apply_member_access_update_deletes_existing_and_adds_rows_when_not_all_boards() -> (
None
):
member = OrganizationMember(id=uuid4(), organization_id=uuid4(), user_id=uuid4(), role="member")
member = OrganizationMember(
id=uuid4(), organization_id=uuid4(), user_id=uuid4(), role="member",
)
update = OrganizationMemberAccessUpdate(
all_boards_read=False,
all_boards_write=False,
board_access=[
OrganizationBoardAccessSpec(board_id=uuid4(), can_read=True, can_write=False),
OrganizationBoardAccessSpec(board_id=uuid4(), can_read=True, can_write=True),
OrganizationBoardAccessSpec(
board_id=uuid4(), can_read=True, can_write=False,
),
OrganizationBoardAccessSpec(
board_id=uuid4(), can_read=True, can_write=True,
),
],
)
session = _FakeSession(exec_results=[])
await organizations.apply_member_access_update(session, member=member, update=update)
await organizations.apply_member_access_update(
session, member=member, update=update,
)
# delete statement executed once
assert len(session.executed) == 1
@@ -330,7 +364,7 @@ async def test_apply_invite_to_member_upgrades_role_and_merges_access_rows(
exec_results=[
[invite_access],
_FakeExecResult(first_value=None),
]
],
)
await organizations.apply_invite_to_member(session, member=member, invite=invite)

5
backend/tests/test_souls_directory.py
View File

@@ -1,9 +1,13 @@
# ruff: noqa: INP001, S101
"""Unit tests for souls-directory parsing and search helpers."""
from __future__ import annotations
from app.services.souls_directory import SoulRef, _parse_sitemap_soul_refs, search_souls
def test_parse_sitemap_extracts_soul_refs() -> None:
"""Sitemap parser should emit only valid soul handle/slug refs."""
xml = """<?xml version="1.0" encoding="UTF-8"?>
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
<url><loc>https://souls.directory</loc></url>
@@ -19,6 +23,7 @@ def test_parse_sitemap_extracts_soul_refs() -> None:
def test_search_souls_matches_handle_or_slug() -> None:
"""Search should match both handle and slug text, case-insensitively."""
refs = [
SoulRef(handle="thedaviddias", slug="code-reviewer"),
SoulRef(handle="thedaviddias", slug="technical-writer"),