Testing architecture overhaul: real-DB fixtures, i18n fixes, and the production bugs they surfaced

CLAUDE.md

@@ -878,12 +878,36 @@ See `docs/CONFIGURATION.md` for complete reference.
 - **Payment tests**: `tests/payment/` - Domain, matchers, services (≥80% coverage required)
 - Use `conftest.py` fixtures for database session, sample data, mock providers
 
+**Database fixtures (testing architecture):**
+- `db_session` / `sample_*` (root `conftest.py`): an in-memory session for direct
+  ORM assertions. Does NOT wire the global session factory — use it when the test
+  itself owns the queries.
+- `runtime_db` / `runtime_session` / `seed_cliente` / `seed_fattura`: point an
+  isolated, file-backed SQLite DB at the GLOBAL session factory AND at
+  `get_settings()` (cedente/PEC/`database_url` via env). Use these whenever the
+  code under test opens its own session — CLI commands (`with db_session() as db:`
+  / `init_db(settings.database_url)`), web services (`db_session_scope`), or agents
+  — so production code and the test share one real database. Prefer seeding real
+  rows over mocking SQLAlchemy query chains. Mock only true external boundaries
+  (LLM providers, PEC/SMTP, LND/gRPC). The `tests/ai` package has an autouse
+  in-memory DB; opt a node test out of session mocking with `@pytest.mark.real_db`.
+- CLI output is i18n (default locale Italian). Tests that assert on rendered text
+  pin the locale with a module-level autouse `_english_locale` fixture and assert
+  the English strings; Rich tables truncate at 80 cols, so use a `_WideCliRunner`
+  (COLUMNS=220) when asserting wide table cells. Typer/Click route usage/argument
+  errors to `result.stderr` (streams are split), not `result.stdout`.
+
 **Test Markers:**
 ```python
 @pytest.mark.streaming     # Streaming-capable components
 @pytest.mark.e2e          # End-to-end tests requiring external services
 @pytest.mark.ollama       # Tests requiring Ollama LLM service
+@pytest.mark.performance  # Wall-clock/benchmark tests
+@pytest.mark.real_db      # Opt out of session mocking, use the real in-memory DB
 ```
+The default `pytest` gate deselects `performance`/`benchmark`/`slow`/`e2e`/`ollama`
+(see `addopts`) so it stays fast and deterministic; run those tiers explicitly,
+e.g. `uv run pytest -m performance` or `uv run pytest -m "ollama and e2e"`.
 
 ## Code Style
 

openfatture/cli/commands/cliente.py

@@ -4,6 +4,7 @@
 from rich.console import Console
 from rich.prompt import Confirm, Prompt
 from rich.table import Table
+from sqlalchemy.exc import SQLAlchemyError
 
 from openfatture.cli.lifespan import get_event_bus
 from openfatture.core.events import ClientCreatedEvent, ClientDeletedEvent
@@ -109,71 +110,77 @@ def add_cliente(
         raise typer.Exit(1)
 
     # Create client
-    with db_session() as db:
-        # Parse name into first and last name if possible
-        nome = None
-        cognome = None
-        if denominazione and " " in denominazione:
-            # Try to split the name into first and last name
-            parts = denominazione.split(" ", 1)
-            if len(parts) == 2:
-                nome = parts[0]
-                cognome = parts[1]
-
-        cliente = Cliente(
-            denominazione=denominazione,
-            nome=nome,
-            cognome=cognome,
-            partita_iva=partita_iva,
-            codice_fiscale=codice_fiscale,
-            codice_destinatario=codice_destinatario,
-            pec=pec,
-            indirizzo=indirizzo if interactive else None,
-            numero_civico=numero_civico if interactive else None,
-            cap=cap if interactive else None,
-            comune=comune if interactive else None,
-            provincia=provincia if interactive else None,
-            nazione="IT",  # Default to Italy
-            email=email if interactive else None,
-            telefono=telefono if interactive else None,
-            note=note if interactive else None,
-        )
-
-        db.add(cliente)
-        db.commit()
-        db.refresh(cliente)
-
-        # Publish ClientCreatedEvent
-        event_bus = get_event_bus()
-        if event_bus:
-            event_bus.publish(
-                ClientCreatedEvent(
-                    client_id=cliente.id,
-                    client_name=cliente.denominazione,
-                    partita_iva=cliente.partita_iva,
-                    codice_fiscale=cliente.codice_fiscale,
-                    codice_destinatario=cliente.codice_destinatario,
-                    pec=cliente.pec,
-                )
+    try:
+        with db_session() as db:
+            # Parse name into first and last name if possible
+            nome = None
+            cognome = None
+            if denominazione and " " in denominazione:
+                # Try to split the name into first and last name
+                parts = denominazione.split(" ", 1)
+                if len(parts) == 2:
+                    nome = parts[0]
+                    cognome = parts[1]
+
+            cliente = Cliente(
+                denominazione=denominazione,
+                nome=nome,
+                cognome=cognome,
+                partita_iva=partita_iva,
+                codice_fiscale=codice_fiscale,
+                codice_destinatario=codice_destinatario,
+                pec=pec,
+                indirizzo=indirizzo if interactive else None,
+                numero_civico=numero_civico if interactive else None,
+                cap=cap if interactive else None,
+                comune=comune if interactive else None,
+                provincia=provincia if interactive else None,
+                nazione="IT",  # Default to Italy
+                email=email if interactive else None,
+                telefono=telefono if interactive else None,
+                note=note if interactive else None,
             )
 
-        console.print(_("cli-cliente-added-success", id=cliente.id))
-
-        # Show summary
-        table = Table(title=_("cli-cliente-table-title", name=denominazione))
-        table.add_column(_("cli-cliente-table-field"), style="cyan")
-        table.add_column(_("cli-cliente-table-value"), style="white")
-
-        if partita_iva:
-            table.add_row(_("cli-cliente-label-piva"), partita_iva)
-        if codice_fiscale:
-            table.add_row(_("cli-cliente-label-cf"), codice_fiscale)
-        if codice_destinatario:
-            table.add_row(_("cli-cliente-label-sdi"), codice_destinatario)
-        if pec:
-            table.add_row(_("cli-cliente-label-pec"), pec)
+            db.add(cliente)
+            db.commit()
+            db.refresh(cliente)
+
+            # Publish ClientCreatedEvent
+            event_bus = get_event_bus()
+            if event_bus:
+                event_bus.publish(
+                    ClientCreatedEvent(
+                        client_id=cliente.id,
+                        client_name=cliente.denominazione,
+                        partita_iva=cliente.partita_iva,
+                        codice_fiscale=cliente.codice_fiscale,
+                        codice_destinatario=cliente.codice_destinatario,
+                        pec=cliente.pec,
+                    )
+                )
 
-        console.print(table)
+            console.print(_("cli-cliente-added-success", id=cliente.id))
+
+            # Show summary
+            table = Table(title=_("cli-cliente-table-title", name=denominazione))
+            table.add_column(_("cli-cliente-table-field"), style="cyan")
+            table.add_column(_("cli-cliente-table-value"), style="white")
+
+            if partita_iva:
+                table.add_row(_("cli-cliente-label-piva"), partita_iva)
+            if codice_fiscale:
+                table.add_row(_("cli-cliente-label-cf"), codice_fiscale)
+            if codice_destinatario:
+                table.add_row(_("cli-cliente-label-sdi"), codice_destinatario)
+            if pec:
+                table.add_row(_("cli-cliente-label-pec"), pec)
+
+            console.print(table)
+    except (SQLAlchemyError, ValueError) as exc:
+        # db_session() has already rolled back; convert the failure into a
+        # clean error message and non-zero exit instead of a raw traceback.
+        console.print(_("cli-cliente-add-error", error=str(exc)))
+        raise typer.Exit(1) from exc
 
 
 @app.command("list")

openfatture/cli/commands/config.py

@@ -1,5 +1,6 @@
 """Configuration management commands."""
 
+from pathlib import Path
 from typing import Any
 
 import typer
@@ -273,8 +274,9 @@ def set_config(
 
             setattr(settings, key, new_val)
 
-        # Save to TOML
-        config_path = dirs.user_config_dir / "config.toml"
+        # Save to TOML. dirs.user_config_dir is a str (platformdirs), so wrap it
+        # in Path before joining.
+        config_path = Path(dirs.user_config_dir) / "config.toml"
         save_config(settings, config_path)
 
         console.print(_("cli-config-set-success", key=key, value=value))

openfatture/cli/commands/fattura.py

@@ -7,6 +7,7 @@
 from rich.console import Console
 from rich.prompt import Confirm, FloatPrompt, IntPrompt, Prompt
 from rich.table import Table
+from sqlalchemy.exc import SQLAlchemyError
 
 from openfatture.cli.lifespan import get_event_bus
 from openfatture.core.events import (
@@ -56,6 +57,19 @@ def crea_fattura(
 
     console.print(f"\n{_('cli-fattura-create-title')}\n")
 
+    try:
+        _crea_fattura_in_db(cliente_id)
+    except (SQLAlchemyError, ValueError) as exc:
+        # db_session() has already rolled back; convert a database/validation
+        # failure into a clean error message and non-zero exit instead of a raw
+        # traceback. typer.Exit raised inside (e.g. no clients) is not caught
+        # here and propagates unchanged.
+        console.print(_("cli-fattura-create-error", error=str(exc)))
+        raise typer.Exit(1) from exc
+
+
+def _crea_fattura_in_db(cliente_id: int | None) -> None:
+    """Run the invoice-creation transaction. Wrapped by ``crea_fattura``."""
     with db_session() as db:
         # Select client
         if not cliente_id:
@@ -80,8 +94,16 @@ def crea_fattura(
 
         console.print(f"{_('cli-fattura-client-selected', client_name=cliente.denominazione)}\n")
 
-        # Invoice details
-        anno = date.today().year
+        # Invoice details. Derive the year from the entered issue date so the
+        # stored ``anno`` (used for FatturaPA numbering/progressivo) stays
+        # consistent with ``data_emissione`` even when the user back-dates or
+        # forward-dates the invoice into another year.
+        data_emissione_input = Prompt.ask(
+            "Issue date (YYYY-MM-DD)", default=date.today().isoformat()
+        )
+        data_emissione = date.fromisoformat(data_emissione_input)
+        anno = data_emissione.year
+
         ultimo_numero = (
             db.query(Fattura).filter(Fattura.anno == anno).order_by(Fattura.numero.desc()).first()
         )
@@ -92,13 +114,12 @@ def crea_fattura(
             prossimo_numero = 1
 
         numero = Prompt.ask("Invoice number", default=str(prossimo_numero))
-        data_emissione = Prompt.ask("Issue date (YYYY-MM-DD)", default=date.today().isoformat())
 
         # Create invoice
         fattura = Fattura(
             numero=numero,
             anno=anno,
-            data_emissione=date.fromisoformat(data_emissione),
+            data_emissione=data_emissione,
             cliente_id=cliente.id,
             tipo_documento=TipoDocumento.TD01,
             stato=StatoFattura.BOZZA,

openfatture/cli/commands/lightning.py

@@ -252,6 +252,10 @@ def compliance_check(
                 )
             console.print()
 
+    except typer.Exit:
+        # Control-flow exit (e.g. compliance issues found): do not report it as
+        # an unexpected error.
+        raise
     except Exception as e:
         console.print(_("cli-lightning-compliance-error", error=str(e)))
         raise typer.Exit(code=1)

openfatture/cli/formatters/stream_json.py

@@ -1,11 +1,14 @@
 """Streaming JSON Lines formatter."""
 
 import json
-from typing import Any
+from typing import TYPE_CHECKING, Any
 
 from openfatture.ai.domain.response import AgentResponse
 from openfatture.cli.formatters.base import BaseFormatter
 
+if TYPE_CHECKING:
+    from openfatture.ai.streaming.events import StreamEvent
+
 
 class StreamJSONFormatter(BaseFormatter):
     """Formatter that outputs responses as JSON Lines (JSONL) format.
@@ -84,28 +87,66 @@ def format_response(self, response: AgentResponse) -> str:
 
         return "\n".join(lines)
 
-    def format_stream_chunk(self, chunk: str) -> str:
+    def format_stream_chunk(self, chunk: "str | StreamEvent") -> str:
         """Format a streaming chunk as JSON Line.
 
         Each chunk is formatted as a separate JSON object with:
         - type: "chunk"
         - content: the chunk text
         - index: sequential chunk number
 
+        Accepts either a plain string (raw text chunk) or a
+        :class:`~openfatture.ai.streaming.events.StreamEvent`, which is what
+        streaming agents such as ``ChatAgent.execute_stream()`` actually yield.
+        For a ``StreamEvent`` the textual payload is extracted (``data`` for
+        content/string events, or its JSON form for structured events) so the
+        emitted JSON line is always serializable.
+
         Args:
-            chunk: A chunk of response content
+            chunk: A chunk of response content (string or StreamEvent)
 
         Returns:
             JSONL formatted chunk with newline
         """
+        content = self._extract_chunk_content(chunk)
         chunk_obj = {
             "type": "chunk",
-            "content": chunk,
+            "content": content,
             "index": self.chunk_index,
         }
         self.chunk_index += 1
         return json.dumps(chunk_obj, ensure_ascii=self.ensure_ascii) + "\n"
 
+    @staticmethod
+    def _extract_chunk_content(chunk: "str | StreamEvent") -> str:
+        """Normalize a stream chunk into a JSON-serializable string.
+
+        Streaming agents yield ``StreamEvent`` objects rather than raw strings.
+        A ``StreamEvent`` is not JSON-serializable on its own, so extract its
+        textual payload: the ``data`` field for string payloads (content,
+        thinking, status, ...) or a compact JSON encoding for structured
+        payloads (tool events, metrics, ...).
+
+        Args:
+            chunk: A raw string chunk or a StreamEvent.
+
+        Returns:
+            A plain string suitable for embedding in the JSON line.
+        """
+        if isinstance(chunk, str):
+            return chunk
+
+        # Lazy import keeps the CLI startup free of the AI stack.
+        from openfatture.ai.streaming.events import StreamEvent
+
+        if isinstance(chunk, StreamEvent):
+            data = chunk.data
+            if isinstance(data, str):
+                return data
+            return json.dumps(data, ensure_ascii=False)
+
+        return str(chunk)
+
     def format_stream_complete(
         self,
         status: str = "success",

openfatture/i18n/loader.py

@@ -54,8 +54,11 @@ def _load_bundle(locale: str) -> FluentBundle:
     if not locale_dir.exists():
         raise FileNotFoundError(f"Locale directory not found: {locale_dir}")
 
-    # Create FluentBundle
-    bundle = FluentBundle([locale])
+    # Create FluentBundle.
+    # use_isolating=False: this app renders Fluent output through Rich markup and
+    # plain CLI/email text, where the Unicode bidi isolation marks (U+2068/U+2069)
+    # that Fluent inserts around placeables corrupt markup and pollute output.
+    bundle = FluentBundle([locale], use_isolating=False)
 
     # Load all .ftl files in the locale directory
     ftl_files = sorted(locale_dir.glob("*.ftl"))