Skip to content

Open-source personal finance manager. Self-hosted, privacy-first.

6.0 KB
Raw Blame
"""Jurisdiction packs: what they may decide, and what they must not.

Two properties carry the whole design and each has a test that fails loudly
if someone erodes it: a pack orders and labels but never forbids, and a
workspace with no jurisdiction is a working configuration rather than a
broken one.
"""
import pytest

from app.fiscal.registry import (
    FALLBACK,
    KIND_SPECS,
    PACK_DIR,
    JurisdictionPack,
    TaxIdKind,
    available_jurisdictions,
    normalise_and_validate,
    pack_for,
    spec_for,
)
from app.fiscal.validators import NORMALISERS, VALIDATORS


# ---------------------------------------------------------------------------
# the packs load and stay well-formed
# ---------------------------------------------------------------------------
def test_initial_jurisdictions_are_available():
    """A subset check, not an equality one: pinning the full list would make
    every contributed pack an edit to this test, which is exactly the friction
    the pack format exists to remove. What matters is that the packs that
    shipped first are still there."""
    available = available_jurisdictions()
    for code in ("BR", "DE", "ES", "FR", "GB", "IT", "PT", "US"):
        assert code in available
    # And the list stays sorted, since the settings selector reads it in order.
    assert available == sorted(available)


def test_every_pack_file_parses_and_only_names_known_kinds():
    """A pack is data: a country code and an ordered list of kinds. It cannot
    define a document, so the only way it breaks is naming one that has no
    spec."""
    for path in PACK_DIR.glob("*.toml"):
        pack = pack_for(path.stem.upper())
        assert isinstance(pack, JurisdictionPack), path.name
        assert pack.code == path.stem.upper(), path.name
        assert pack.kinds, path.name
        for kind in pack.kinds:
            assert kind in KIND_SPECS, (path.name, kind)


def test_every_kind_has_exactly_one_definition():
    """A document is defined once, in code, and used identically everywhere."""
    assert set(KIND_SPECS) == set(TaxIdKind)
    for kind, spec in KIND_SPECS.items():
        assert spec.kind is kind
        assert spec.normalise in NORMALISERS, kind
        assert spec.validate in VALIDATORS, kind
        assert spec.label_key == f"fiscal.kind.{kind.value}", kind


def test_every_pack_offers_other_last():
    """The escape hatch is always present, so any jurisdiction can hold a
    document its pack never anticipated."""
    for code in available_jurisdictions():
        assert pack_for(code).kinds[-1] is TaxIdKind.OTHER, code


def test_pack_order_drives_the_default():
    assert pack_for("BR").kinds[0] is TaxIdKind.CNPJ
    assert pack_for("US").kinds[0] is TaxIdKind.EIN
    assert pack_for("DE").kinds[0] is TaxIdKind.VAT


def test_a_pack_cannot_change_what_a_document_is():
    """The invariant this design turns on: normalisation and validation come
    from the kind, so the same document behaves identically no matter which
    jurisdiction is holding it. An earlier version let packs carry their own
    normaliser and a German VAT number came out spaced differently depending
    on the workspace."""
    for jurisdiction in ("BR", "DE", "GB", "ZZ", None):
        stored, error = normalise_and_validate(TaxIdKind.VAT, "de 123 456 789")
        assert (stored, error) == ("DE123456789", None), jurisdiction


# ---------------------------------------------------------------------------
# no pack is a working configuration
# ---------------------------------------------------------------------------
@pytest.mark.parametrize("jurisdiction", [None, "", "ZZ", "Atlantis"])
def test_unset_or_unshipped_jurisdiction_falls_back(jurisdiction):
    assert pack_for(jurisdiction) is FALLBACK


def test_fallback_stores_free_text_without_validating():
    stored, error = normalise_and_validate(TaxIdKind.OTHER, "  ABC-123/x  ")
    assert stored == "ABC-123/x"
    assert error is None


def test_a_country_without_a_pack_can_still_hold_its_document():
    """The point of the fallback: nobody waits for a pull request to use
    the product."""
    stored, error = normalise_and_validate(TaxIdKind.OTHER, "TIN 99-8877")
    assert error is None and stored == "TIN 99-8877"


# ---------------------------------------------------------------------------
# a pack suggests, it never restricts
# ---------------------------------------------------------------------------
def test_a_kind_outside_the_pack_is_still_storable():
    """A BR workspace billing a Berlin client needs `vat`, and the BR pack
    must not be able to forbid it. This is the test that keeps the product
    usable across borders."""
    assert TaxIdKind.VAT not in pack_for("BR").kinds
    stored, error = normalise_and_validate(TaxIdKind.VAT, "DE 123 456 789")
    assert error is None
    assert stored == "DE123456789"


def test_a_kind_outside_the_pack_keeps_its_own_rules():
    """Storable anywhere does not mean unchecked. A US workspace can hold a
    Codice Fiscale, and it is still validated as one."""
    assert TaxIdKind.CODICE_FISCALE not in pack_for("US").kinds
    assert spec_for(TaxIdKind.CODICE_FISCALE).validate == "it_codice_fiscale"
    _, error = normalise_and_validate(TaxIdKind.CODICE_FISCALE, "too short")
    assert error == "length"


# ---------------------------------------------------------------------------
# normalisation is per kind, and it is what gets stored
# ---------------------------------------------------------------------------
@pytest.mark.parametrize(
    "kind,raw,expected",
    [
        (TaxIdKind.CNPJ, "11.222.333/0001-81", "11222333000181"),
        (TaxIdKind.CPF, "529.982.247-25", "52998224725"),
        (TaxIdKind.VAT, "de 123 456 789", "DE123456789"),
        (TaxIdKind.EIN, "12-3456789", "123456789"),
    ],
)
def test_values_are_stored_normalised(kind, raw, expected):
    stored, error = normalise_and_validate(kind, raw)
    assert (stored, error) == (expected, None)


def test_empty_value_is_refused():
    _, error = normalise_and_validate(TaxIdKind.OTHER, "   ")
    assert error == "empty"