feat: Add InjectByTag support and global TagRegistry for testing

BREAKING CHANGE: Tag registry moved from per-container to global EllarInjector.tag_registry

Features:
- Add InjectByTag dependency resolution in Test.create_test_module()
- Implement get_type_from_tag() to resolve tagged providers from module metadata
- Add import string support for application_module parameter (e.g., app.module:ApplicationModule)
- Add __repr__ and __str__ methods to ProviderConfig for better debugging

Refactoring:
- Extract tag management into new TagRegistry class
- Make TagRegistry a class attribute of EllarInjector for global tag storage
- Remove Container._bindings_by_tag and Container.get_interface_by_tag()
- Tags now registered globally instead of per-container hierarchy

Documentation:
- Update testing.md with comprehensive usage examples
- Add InjectByTag testing patterns
- Document both override methods (override_provider and mock modules)
- Add practical testing patterns (integration, partial mocking, isolation)
- Include nested dependencies and error message examples

Author: eadwinCode

docs/basics/testing.md

@@ -279,7 +279,7 @@ async def add_authentication_schemes(
 
     def get_module_loaders(self) -> t.Generator[ModuleTemplating, None, None]:
         for loader in self._injector.get_templating_modules().values():
-            yield loader
+            yield t.cast(ModuleTemplating, loader)
 
     def _create_jinja_environment(self) -> Environment:
         # TODO: rename to `create_jinja_environment`

ellar/app/main.py

@@ -147,17 +147,17 @@ def exports(self) -> t.List[t.Type]:
         return list(reflect.get_metadata(MODULE_METADATA.EXPORTS, self.module) or [])
 
     @cached_property
-    def providers(self) -> t.Dict[t.Type, t.Type]:
+    def providers(self) -> t.Dict[t.Type, ProviderConfig]:
         _providers = list(
             reflect.get_metadata(MODULE_METADATA.PROVIDERS, self.module) or []
         )
-        res = {}
+        res: t.Dict[t.Type, ProviderConfig] = {}
         for item in _providers:
             if isinstance(item, ProviderConfig):
-                res.update({item: item.get_type()})
+                res.update({item.get_type(): item})
             else:
-                res.update({item: item})
-        return res  # type:ignore[return-value]
+                res.update({item: ProviderConfig(item)})
+        return res
 
     @property
     def is_ready(self) -> bool:

ellar/core/modules/config.py

@@ -33,7 +33,6 @@ class Container(InjectorBinder):
         "injector",
         "_auto_bind",
         "_bindings",
-        "_bindings_by_tag",
         "parent",
         "_aliases",
         "_exact_aliases",
@@ -43,7 +42,6 @@ class Container(InjectorBinder):
 
     def __init__(self, *args: t.Any, **kwargs: t.Any) -> None:
         super().__init__(*args, **kwargs)
-        self._bindings_by_tag: t.Dict[str, t.Type[t.Any]] = {}
 
     @t.no_type_check
     def create_binding(
@@ -58,22 +56,13 @@ def create_binding(
             scope = scope.scope
         return Binding(interface, provider, scope)
 
-    def get_interface_by_tag(self, tag: str) -> t.Type[t.Any]:
-        interface = self._bindings_by_tag.get(tag)
-        if interface:
-            return interface
-        if isinstance(self.parent, Container):
-            return self.parent.get_interface_by_tag(tag)
-
-        raise UnsatisfiedRequirement(None, t.cast(t.Any, tag))
-
     def register_binding(
         self, interface: t.Type, binding: Binding, tag: t.Optional[str] = None
     ) -> None:
         self._bindings[interface] = binding
 
         if tag:
-            self._bindings_by_tag[tag] = interface
+            self.injector.tag_registry.register(tag, interface)
 
     @t.no_type_check
     def register(

ellar/di/injector/container.py

@@ -1,22 +1,26 @@
+from __future__ import annotations
+
 import sys
 import typing as t
 from functools import cached_property
 
 from ellar.di.constants import MODULE_REF_TYPES, Tag, request_context_var
 from ellar.di.injector.tree_manager import ModuleTreeManager
 from ellar.di.logger import log
+from ellar.di.providers import InstanceProvider, Provider
+from ellar.di.types import T
 from injector import Injector, Scope, ScopeDecorator
 from typing_extensions import Annotated
 
-from ..providers import InstanceProvider, Provider
-from ..types import T
 from .container import Container
+from .tag_registry import TagRegistry
 
 if t.TYPE_CHECKING:  # pragma: no cover
     from ellar.core.modules import (
         ModuleBase,
+        ModuleForwardRef,
         ModuleRefBase,
-        ModuleTemplateRef,
+        ModuleSetup,
     )
 
 
@@ -62,6 +66,9 @@ class EllarInjector(Injector):
         "owner",
     )
 
+    # Global tag registry shared across all injector instances
+    tag_registry: t.ClassVar[TagRegistry] = TagRegistry()
+
     def __init__(
         self,
         auto_bind: bool = True,
@@ -101,9 +108,11 @@ def get_module(self, module: t.Type) -> t.Optional["ModuleRefBase"]:
 
     def get_templating_modules(
         self,
-    ) -> t.Dict[t.Type["ModuleBase"], "ModuleTemplateRef"]:
+    ) -> dict[
+        type[ModuleBase] | type, ModuleRefBase | "ModuleSetup" | ModuleForwardRef
+    ]:
         return {
-            item.value.module: item.value  # type:ignore[misc]
+            item.value.module: item.value
             for item in self.tree_manager.get_by_ref_type(MODULE_REF_TYPES.TEMPLATE)
         }
 
@@ -115,7 +124,7 @@ def get(
     ) -> T:
         data = _tag_info_interface(interface)
         if data and data.supertype is Tag:
-            interface = self.container.get_interface_by_tag(data.tag)
+            interface = self.tag_registry.get_interface(data.tag)
 
         binding, binder = self.container.get_binding(interface)
         scope = binding.scope

ellar/di/injector/ellar_injector.py

@@ -0,0 +1,62 @@
+"""
+Tag Registry for managing global tag-to-interface mappings
+"""
+
+import typing as t
+
+from ellar.di.exceptions import UnsatisfiedRequirement
+
+
+class TagRegistry:
+    """
+    Centralized registry for managing tag-to-interface mappings.
+
+    This ensures that all tagged providers are registered globally and accessible
+    across the entire injector hierarchy, rather than being scoped to individual containers.
+    """
+
+    def __init__(self) -> None:
+        self._bindings_by_tag: t.Dict[str, t.Type[t.Any]] = {}
+
+    def register(self, tag: str, interface: t.Type[t.Any]) -> None:
+        """
+        Register a tag-to-interface mapping.
+
+        :param tag: The tag string
+        :param interface: The interface/type associated with this tag
+        """
+        self._bindings_by_tag[tag] = interface
+
+    def get_interface(self, tag: str) -> t.Type[t.Any]:
+        """
+        Get the interface associated with a tag.
+
+        :param tag: The tag string to lookup
+        :return: The interface/type associated with the tag
+        :raises UnsatisfiedRequirement: If the tag is not registered
+        """
+        interface = self._bindings_by_tag.get(tag)
+        if interface:
+            return interface
+
+        raise UnsatisfiedRequirement(None, t.cast(t.Any, tag))
+
+    def has_tag(self, tag: str) -> bool:
+        """
+        Check if a tag is registered.
+
+        :param tag: The tag string to check
+        :return: True if the tag is registered, False otherwise
+        """
+        return tag in self._bindings_by_tag
+
+    def clear(self) -> None:
+        """Clear all tag registrations. Useful for testing."""
+        self._bindings_by_tag.clear()
+
+    def get_all_tags(self) -> t.Dict[str, t.Type[t.Any]]:
+        """Get a copy of all tag-to-interface mappings."""
+        return self._bindings_by_tag.copy()
+
+    def __repr__(self) -> str:
+        return f"TagRegistry(tags={list(self._bindings_by_tag.keys())})"

ellar/di/injector/tag_registry.py

@@ -116,6 +116,66 @@ def __init__(
         self.export = export
         self.core = core
 
+    def __repr__(self) -> str:
+        """Developer-friendly representation showing all configuration details"""
+        parts = [f"base_type={self._type_repr(self.base_type)}"]
+
+        if self.use_value is not None:
+            parts.append(f"use_value={self._type_repr(self.use_value)}")
+        if self.use_class is not None:
+            parts.append(f"use_class={self._type_repr(self.use_class)}")
+        if self.scope != SingletonScope:
+            parts.append(f"scope={self._type_repr(self.scope)}")
+        if self.tag:
+            parts.append(f"tag={self.tag!r}")
+        if self.export:
+            parts.append("export=True")
+        if self.core:
+            parts.append("core=True")
+
+        return f"ProviderConfig({', '.join(parts)})"
+
+    def __str__(self) -> str:
+        """User-friendly string representation"""
+        base = self._type_name(self.base_type)
+
+        if self.use_class:
+            impl = self._type_name(self.use_class)
+            desc = f"{base} -> {impl}"
+        elif self.use_value is not None:
+            desc = f"{base} -> <value>"
+        else:
+            desc = base
+
+        if self.tag:
+            desc = f"{desc} [tag:{self.tag}]"
+
+        return desc
+
+    @staticmethod
+    def _type_repr(obj: t.Any) -> str:
+        """Get a repr-style string for a type or value"""
+        if isinstance(obj, type):
+            return (
+                f"{obj.__module__}.{obj.__qualname__}"
+                if hasattr(obj, "__module__")
+                else obj.__qualname__
+            )
+        elif isinstance(obj, str):
+            return repr(obj)
+        else:
+            return repr(obj)
+
+    @staticmethod
+    def _type_name(obj: t.Any) -> str:
+        """Get a simple name for a type or value"""
+        if isinstance(obj, type):
+            return obj.__qualname__ if hasattr(obj, "__qualname__") else obj.__name__
+        elif isinstance(obj, str):
+            return obj
+        else:
+            return type(obj).__name__
+
     def get_type(self) -> t.Type:
         return self._resolve_type(self.base_type)