docs(tests): explain why relationship tests mock the query builder

The masoniteorm relationship classes are not wired to this fork's async
QueryBuilder, so the relationship unit tests mock the builder instead of
running against real sqlite. Document the specifics inline (missing
QueryBuilder.table()/without_global_scopes()/add_select(), the
BaseRelationship.get_builder() no-arg self.fn() TypeError, the attach/detach
Pivot chain, and the MorphOne/MorphToMany undefined load_config) so the intent
is clear and the framework gaps are traceable. No behavioral or framework
changes.

Author: tmgbedu

fastapi_startkit/tests/masoniteorm/relationships/conftest.py

@@ -1,3 +1,23 @@
+"""Shared test doubles for the relationship unit tests.
+
+``make_builder`` returns a chainable mock standing in for masoniteorm's async
+``QueryBuilder``. The relationship classes are unit-tested against this mock
+rather than real sqlite because they are not currently wired to the fork's async
+``QueryBuilder``:
+
+* the builder (``masoniteorm/models/builder.py``) lacks ``table()``,
+  ``without_global_scopes()`` and ``add_select()``, all called by
+  ``BelongsToMany``;
+* ``BaseRelationship.get_builder()`` calls ``self.fn()`` with no args against
+  ``BelongsToMany``'s ``lambda x:`` factory, raising ``TypeError``;
+* ``attach``/``detach`` chain those same missing methods on a plain ``Pivot``
+  model.
+
+The ``CHAINABLE`` list below mirrors exactly the builder methods the relationship
+code expects, so the relationship logic can be tested in isolation. Real-DB
+wiring is tracked in the project backlog.
+"""
+
 from unittest.mock import AsyncMock, MagicMock
 
 

fastapi_startkit/tests/masoniteorm/relationships/test_base_relationship.py

@@ -1,3 +1,13 @@
+"""Unit tests for the abstract ``BaseRelationship`` contract.
+
+These tests assert ``BaseRelationship``'s key handling and that its abstract
+hooks raise ``NotImplementedError``. The join-clause test mocks the query builder
+(see ``conftest.make_builder``) because this fork's async ``QueryBuilder`` is not
+wired for the relationship builder chain (it lacks ``table()`` /
+``without_global_scopes()`` / ``add_select()``); this is documented for the whole
+relationships suite in ``conftest.py``.
+"""
+
 from unittest.mock import MagicMock
 
 import pytest

fastapi_startkit/tests/masoniteorm/relationships/test_belongs_to_many.py

@@ -1,3 +1,28 @@
+"""Unit tests for :class:`BelongsToMany`, run against a mocked query builder.
+
+These tests mock the query builder (see ``conftest.make_builder``) instead of
+running against real sqlite because ``BelongsToMany`` is not currently wired to
+this fork's async ``QueryBuilder``. A real many-to-many fixture already exists
+(``Store``/``Product`` + the ``product_store`` pivot in ``fixtures/migration.py``),
+so the blocker is framework wiring, not test data:
+
+* The async ``QueryBuilder`` (``masoniteorm/models/builder.py``) does not implement
+  ``table()``, ``without_global_scopes()`` or ``add_select()``, all of which
+  ``BelongsToMany`` calls (e.g. ``BelongsToMany.py`` lines 78, 227, 463). Real
+  access/eager-load/``where_has`` raise ``AttributeError``.
+* ``BaseRelationship.get_builder()`` calls ``self.fn()`` with no arguments while
+  ``BelongsToMany.__init__`` assigns ``self.fn = lambda x: ...``, so resolving the
+  related builder raises ``TypeError: <lambda>() missing 1 required positional
+  argument: 'x'``.
+* ``attach``/``detach`` chain ``Pivot.on(...).table(...).without_global_scopes()
+  .create(...)`` on a plain ``Pivot`` model that has none of those chainable
+  builder methods, so the chain resolves to ``None`` and raises ``TypeError``.
+
+Mocking the builder lets these tests exercise the relationship's own logic (key
+inference, pivot hydration, join/select construction) in isolation. Wiring the
+async ``QueryBuilder`` for real-DB coverage is tracked in the project backlog.
+"""
+
 from unittest.mock import MagicMock, patch
 
 

fastapi_startkit/tests/masoniteorm/relationships/test_morph_relations.py

@@ -1,3 +1,15 @@
+"""Unit tests for the polymorphic relationships (MorphOne/MorphMany/MorphToMany/MorphTo).
+
+``MorphOne`` and ``MorphToMany`` are tested with mocks because their
+``morph_map()`` implementations reference an undefined ``load_config`` name
+(``MorphOne.py`` line 134, ``MorphToMany.py`` line 103) and raise ``NameError``
+when called for real. ``MorphMany`` is likewise mocked: its resolved builder is
+not wired to this fork's async ``QueryBuilder``. ``MorphTo`` does work against
+real sqlite and is additionally covered end-to-end in
+``sqlite/relationships/test_sqlite_polymorphic.py``. The framework fixes needed
+for real-DB coverage of the other morphs are tracked in the project backlog.
+"""
+
 from unittest.mock import MagicMock
 
 import pytest