Open-source personal finance manager. Self-hosted, privacy-first.
"""The rendered document: resolution, PDF bytes, and the shared link.
Two properties matter most here and both are asserted directly:
1. **The snapshot wins.** A document already in a client's hands must
not change when settings do.
2. **The screen and the PDF agree.** They consume one structure, and
the tests read that structure rather than either renderer.
"""
import uuid
from datetime import date, timedelta
from decimal import Decimal
import pytest
import pytest_asyncio
from httpx import AsyncClient
from sqlalchemy.ext.asyncio import AsyncSession
from app.fiscal.registry import TaxIdKind, apply_mask, format_for_display
from app.models.payee import Payee, PayeeTaxId
from app.services import invoice_pdf
TODAY = date.today()
@pytest_asyncio.fixture
async def business_ws(client: AsyncClient, auth_headers) -> dict:
resp = await client.post(
"/api/workspaces",
headers=auth_headers,
json={"name": "Consultoria", "kind": "business", "self_membership": True},
)
assert resp.status_code == 201, resp.text
return resp.json()
@pytest_asyncio.fixture
async def biz_headers(auth_headers, business_ws) -> dict:
return {**auth_headers, "X-Workspace-Id": business_ws["id"]}
@pytest_asyncio.fixture
async def client_payee(session: AsyncSession, business_ws, test_user) -> Payee:
payee = Payee(
id=uuid.uuid4(), user_id=test_user.id, workspace_id=uuid.UUID(business_ws["id"]),
name="Beta Tecnologia LTDA", source="manual", address="Av Paulista, 1000",
email="[email protected]",
)
session.add(payee)
await session.flush()
session.add(
PayeeTaxId(
payee_id=payee.id, workspace_id=uuid.UUID(business_ws["id"]),
kind="cnpj", value="11222333000181",
)
)
await session.commit()
return payee
async def make_invoice(client, headers, **overrides):
payload = {
"total": "3000.00",
"due_date": str(TODAY + timedelta(days=15)),
"lines": [{"description": "Consultoria", "quantity": "10", "unit_price": "300.00"}],
}
payload.update(overrides)
resp = await client.post("/api/invoices", headers=headers, json=payload)
assert resp.status_code == 201, resp.text
return resp.json()
# ---------------------------------------------------------------------------
# The mask, shared by the PDF and the screen
# ---------------------------------------------------------------------------
class TestMask:
def test_formats_a_full_document(self):
assert format_for_display(TaxIdKind.CNPJ, "11222333000181") == "11.222.333/0001-81"
assert format_for_display(TaxIdKind.CPF, "52998224725") == "529.982.247-25"
def test_shows_a_short_value_as_stored(self):
"""A half-masked document number ("12.3") reads as corruption. If
the value does not fill the mask, it is shown as it is."""
assert apply_mask("123", "##.###.###/####-##") == "123"
def test_shows_a_long_value_as_stored(self):
assert apply_mask("1122233300018199", "##.###.###/####-##") == "1122233300018199"
def test_a_kind_with_no_mask_is_untouched(self):
# Which is what keeps a jurisdiction nobody has described from
# being mangled.
assert apply_mask("DE811907980", None) == "DE811907980"
# ---------------------------------------------------------------------------
# Document resolution
# ---------------------------------------------------------------------------
@pytest.mark.asyncio
class TestDocument:
async def test_carries_both_parties_and_the_lines(
self, client: AsyncClient, biz_headers, client_payee
):
await client.patch(
"/api/invoices/issuer",
headers=biz_headers,
json={
"legal_name": "Alpha Consultoria ME",
"address": "Rua das Flores, 10",
"tax_ids": [{"kind": "cnpj", "value": "11.222.333/0001-81"}],
},
)
invoice = await make_invoice(client, biz_headers, payee_id=str(client_payee.id))
resp = await client.get(f"/api/invoices/{invoice['id']}/document", headers=biz_headers)
assert resp.status_code == 200, resp.text
doc = resp.json()
assert doc["issuer"]["legal_name"] == "Alpha Consultoria ME"
# Masked server-side: the PDF has no frontend to ask.
assert doc["issuer"]["tax_ids"][0]["value"] == "11.222.333/0001-81"
assert doc["client"]["name"] == "Beta Tecnologia LTDA"
assert doc["client"]["tax_ids"][0]["value"] == "11.222.333/0001-81"
assert doc["lines"][0]["description"] == "Consultoria"
assert doc["total"] == "3000.00"
assert doc["has_line_items"] is True
async def test_an_invoice_with_no_lines_says_so(self, client: AsyncClient, biz_headers):
"""The majority Brazilian case: the NF was issued at the
prefeitura and this is only tracking the money. It must not
pretend to be a document."""
invoice = await make_invoice(client, biz_headers, lines=[])
resp = await client.get(f"/api/invoices/{invoice['id']}/document", headers=biz_headers)
assert resp.json()["has_line_items"] is False
assert resp.json()["lines"] == []
async def test_labels_default_and_can_be_overridden(
self, client: AsyncClient, biz_headers
):
# The conftest user reads pt-BR, so the workspace does too and the
# document defaults to the Portuguese pack. Asserted against the
# pack rather than a hardcoded word: the point is that the issuer's
# language decides, not which language that happens to be.
from app.services.invoice_document import default_labels
default = await make_invoice(client, biz_headers)
doc = (
await client.get(f"/api/invoices/{default['id']}/document", headers=biz_headers)
).json()
assert doc["labels"]["quantity"] == default_labels("pt-BR")["quantity"]
await client.patch(
"/api/invoices/settings",
headers=biz_headers,
json={"template": {"labels": {"quantity": "Horas", "invoice": "Fatura"}}},
)
customised = await make_invoice(client, biz_headers)
doc = (
await client.get(f"/api/invoices/{customised['id']}/document", headers=biz_headers)
).json()
assert doc["labels"]["quantity"] == "Horas"
assert doc["labels"]["invoice"] == "Fatura"
# Untouched labels keep their default rather than disappearing.
assert doc["labels"]["total"] == default_labels("pt-BR")["total"]
async def test_an_unknown_label_key_is_ignored(self, client: AsyncClient, biz_headers):
"""The template is free-form jsonb, so it can hold anything a hand
edit put there. Unknown keys must not become UI."""
await client.patch(
"/api/invoices/settings",
headers=biz_headers,
json={"template": {"labels": {"nonsense": "x", "quantity": "Horas"}}},
)
invoice = await make_invoice(client, biz_headers)
doc = (
await client.get(f"/api/invoices/{invoice['id']}/document", headers=biz_headers)
).json()
assert "nonsense" not in doc["labels"]
assert doc["labels"]["quantity"] == "Horas"
async def test_the_snapshot_beats_later_settings(
self, client: AsyncClient, biz_headers, client_payee
):
"""The rule the whole design turns on: a document in a client's
hands does not change when the sender edits their profile."""
await client.patch(
"/api/invoices/settings",
headers=biz_headers,
json={"issuer_display_name": "Alpha ME", "accent_color": "#4f46e5",
"payment_details": "Pix: [email protected]"},
)
invoice = await make_invoice(client, biz_headers, payee_id=str(client_payee.id))
await client.patch(
"/api/invoices/settings",
headers=biz_headers,
json={"issuer_display_name": "Gamma LTDA", "accent_color": "#dc2626",
"payment_details": "Pix: [email protected]"},
)
doc = (
await client.get(f"/api/invoices/{invoice['id']}/document", headers=biz_headers)
).json()
assert doc["issuer"]["name"] == "Alpha ME"
assert doc["accent_color"] == "#4f46e5"
assert doc["payment_details"] == "Pix: [email protected]"
async def test_renaming_a_client_does_not_rewrite_their_document(
self, client: AsyncClient, biz_headers, client_payee, session: AsyncSession
):
invoice = await make_invoice(client, biz_headers, payee_id=str(client_payee.id))
await client.patch(
f"/api/payees/{client_payee.id}", headers=biz_headers, json={"name": "Beta S.A."}
)
doc = (
await client.get(f"/api/invoices/{invoice['id']}/document", headers=biz_headers)
).json()
assert doc["client"]["name"] == "Beta Tecnologia LTDA"
async def test_custom_fields_follow_the_definitions(
self, client: AsyncClient, biz_headers
):
await client.patch(
"/api/invoices/settings",
headers=biz_headers,
json={"template": {"custom_fields": [{"key": "po", "label": "PO number"}]}},
)
invoice = await make_invoice(
client, biz_headers, custom_fields={"po": "PO-4471", "stray": "ignored"}
)
doc = (
await client.get(f"/api/invoices/{invoice['id']}/document", headers=biz_headers)
).json()
# Driven by the definitions, so a value with no definition never
# reaches the page.
assert doc["custom_fields"] == [{"label": "PO number", "value": "PO-4471"}]
# ---------------------------------------------------------------------------
# PDF
# ---------------------------------------------------------------------------
class TestPdf:
async def test_downloads_a_real_pdf(self, client: AsyncClient, biz_headers, client_payee):
invoice = await make_invoice(client, biz_headers, payee_id=str(client_payee.id))
resp = await client.get(f"/api/invoices/{invoice['id']}/pdf", headers=biz_headers)
assert resp.status_code == 200, resp.text
assert resp.headers["content-type"] == "application/pdf"
assert resp.content.startswith(b"%PDF-")
assert "attachment" in resp.headers["content-disposition"]
async def test_the_pdf_carries_what_the_document_says(
self, client: AsyncClient, biz_headers, client_payee
):
"""Read back through pypdf rather than trusting the byte count:
a PDF that renders blank is still a valid PDF."""
import pypdf
await client.patch(
"/api/invoices/issuer",
headers=biz_headers,
json={"legal_name": "Alpha Consultoria ME",
"tax_ids": [{"kind": "cnpj", "value": "11222333000181"}]},
)
invoice = await make_invoice(client, biz_headers, payee_id=str(client_payee.id))
resp = await client.get(f"/api/invoices/{invoice['id']}/pdf", headers=biz_headers)
import io
text = pypdf.PdfReader(io.BytesIO(resp.content)).pages[0].extract_text()
assert "Beta Tecnologia LTDA" in text
assert "Alpha Consultoria ME" in text
assert "11.222.333/0001-81" in text
assert "Consultoria" in text
assert "3,000.00" in text
assert invoice["due_date"] in text
async def test_renders_without_a_client_or_any_profile(
self, client: AsyncClient, biz_headers
):
"""A workspace that has filled nothing in still gets a usable
page — every field on the document is optional by design."""
invoice = await make_invoice(client, biz_headers, lines=[])
resp = await client.get(f"/api/invoices/{invoice['id']}/pdf", headers=biz_headers)
assert resp.status_code == 200
assert resp.content.startswith(b"%PDF-")
def test_a_broken_accent_colour_degrades_instead_of_raising(self):
"""User input reaching a renderer must never cost the document."""
from app.services.invoice_pdf import _accent
assert _accent("not-a-colour") is not None
assert _accent(None) is not None
assert _accent("#4f46e5") is not None
async def test_a_broken_logo_does_not_cost_the_document(
self, client: AsyncClient, biz_headers
):
invoice = await make_invoice(client, biz_headers)
settings = (await client.get("/api/invoices/settings", headers=biz_headers)).json()
doc_resp = await client.get(
f"/api/invoices/{invoice['id']}/document", headers=biz_headers
)
assert doc_resp.status_code == 200
# Feed the renderer bytes that are not an image at all.
from app.services.invoice_document import (
DEFAULT_LABELS, DocumentParty, InvoiceDocument,
)
document = InvoiceDocument(
number="1", status="open", state="open", issue_date=TODAY, due_date=TODAY,
currency="USD", subtotal=Decimal("0"), discount=Decimal("0"),
tax_total=Decimal("0"), total=Decimal("10"), amount_paid=Decimal("0"),
amount_deducted=Decimal("0"), balance=Decimal("10"), issuer=DocumentParty(name="A"),
client=DocumentParty(name="B"), lines=[], labels=dict(DEFAULT_LABELS),
accent_color="#000000", logo_id=None, payment_details=None, notes=None,
footer_note=None, custom_fields=[], has_line_items=False,
)
pdf = invoice_pdf.render_pdf(document, logo_bytes=b"not an image")
assert pdf.startswith(b"%PDF-")
assert settings is not None
# ---------------------------------------------------------------------------
# Sharing — the only unauthenticated surface
# ---------------------------------------------------------------------------
@pytest.mark.asyncio
class TestSharing:
async def test_a_link_serves_the_document_without_auth(
self, client: AsyncClient, biz_headers, client_payee
):
invoice = await make_invoice(client, biz_headers, payee_id=str(client_payee.id))
created = await client.post(f"/api/invoices/{invoice['id']}/share", headers=biz_headers)
assert created.status_code == 201, created.text
token = created.json()["token"]
assert created.json()["path"] == f"/i/{token}"
# No Authorization header at all.
public = await client.get(f"/api/public/invoices/{token}")
assert public.status_code == 200, public.text
assert public.json()["client"]["name"] == "Beta Tecnologia LTDA"
async def test_the_public_view_leaks_nothing_internal(
self, client: AsyncClient, biz_headers, client_payee
):
invoice = await make_invoice(
client, biz_headers, payee_id=str(client_payee.id),
internal_notes="cliente reclamou do prazo",
)
token = (
await client.post(f"/api/invoices/{invoice['id']}/share", headers=biz_headers)
).json()["token"]
body = (await client.get(f"/api/public/invoices/{token}")).text
assert "cliente reclamou" not in body
assert "internal_notes" not in body
assert "allocations" not in body
assert "payee_id" not in body
async def test_the_token_is_not_derived_from_the_id(
self, client: AsyncClient, biz_headers
):
invoice = await make_invoice(client, biz_headers)
token = (
await client.post(f"/api/invoices/{invoice['id']}/share", headers=biz_headers)
).json()["token"]
assert invoice["id"].replace("-", "") not in token
assert len(token) >= 32
async def test_asking_twice_returns_the_same_link(
self, client: AsyncClient, biz_headers
):
"""Otherwise every visit to the invoice page would silently
invalidate the link the client was already sent."""
invoice = await make_invoice(client, biz_headers)
first = await client.post(f"/api/invoices/{invoice['id']}/share", headers=biz_headers)
second = await client.post(f"/api/invoices/{invoice['id']}/share", headers=biz_headers)
assert first.json()["token"] == second.json()["token"]
async def test_revoking_makes_the_link_a_404(self, client: AsyncClient, biz_headers):
invoice = await make_invoice(client, biz_headers)
token = (
await client.post(f"/api/invoices/{invoice['id']}/share", headers=biz_headers)
).json()["token"]
assert (await client.get(f"/api/public/invoices/{token}")).status_code == 200
revoked = await client.delete(f"/api/invoices/{invoice['id']}/share", headers=biz_headers)
assert revoked.status_code == 204
# Indistinguishable from a link that never existed.
assert (await client.get(f"/api/public/invoices/{token}")).status_code == 404
async def test_voiding_takes_the_link_down(self, client: AsyncClient, biz_headers):
"""A cancelled document must stop being served: a link that keeps
working says the invoice still stands."""
invoice = await make_invoice(client, biz_headers)
token = (
await client.post(f"/api/invoices/{invoice['id']}/share", headers=biz_headers)
).json()["token"]
await client.post(f"/api/invoices/{invoice['id']}/void", headers=biz_headers)
assert (await client.get(f"/api/public/invoices/{token}")).status_code == 404
async def test_a_draft_cannot_be_shared(self, client: AsyncClient, biz_headers):
await client.patch(
"/api/invoices/settings", headers=biz_headers, json={"preset": "document"}
)
draft = await make_invoice(client, biz_headers)
assert draft["status"] == "draft"
resp = await client.post(f"/api/invoices/{draft['id']}/share", headers=biz_headers)
assert resp.status_code == 400
assert resp.json()["detail"]["code"] == "draft_not_shareable"
async def test_an_unknown_token_is_a_404(self, client: AsyncClient):
assert (await client.get("/api/public/invoices/nope")).status_code == 404
async def test_the_public_pdf_opens_inline(self, client: AsyncClient, biz_headers):
invoice = await make_invoice(client, biz_headers)
token = (
await client.post(f"/api/invoices/{invoice['id']}/share", headers=biz_headers)
).json()["token"]
resp = await client.get(f"/api/public/invoices/{token}/pdf")
assert resp.status_code == 200
assert resp.content.startswith(b"%PDF-")
# Someone opening a link expects to see the document, not to
# receive a download.
assert "inline" in resp.headers["content-disposition"]
# ---------------------------------------------------------------------------
# Issuer identity (T10)
# ---------------------------------------------------------------------------
@pytest.mark.asyncio
class TestIssuerProfile:
async def test_stores_and_normalises_a_document(self, client: AsyncClient, biz_headers):
resp = await client.patch(
"/api/invoices/issuer",
headers=biz_headers,
json={"legal_name": "Alpha ME",
"tax_ids": [{"kind": "cnpj", "value": "11.222.333/0001-81"}]},
)
assert resp.status_code == 200, resp.text
# Stored normalised, exactly as the payee side stores it.
assert resp.json()["tax_ids"][0]["value"] == "11222333000181"
async def test_refuses_an_invalid_document_with_the_same_validator(
self, client: AsyncClient, biz_headers
):
"""One implementation, asserted from both call sites."""
resp = await client.patch(
"/api/invoices/issuer",
headers=biz_headers,
json={"tax_ids": [{"kind": "cnpj", "value": "11111111111111"}]},
)
assert resp.status_code == 400
assert resp.json()["detail"]["code"].startswith("invalid_tax_id:cnpj")
async def test_sending_a_shorter_list_removes_a_document(
self, client: AsyncClient, biz_headers
):
await client.patch(
"/api/invoices/issuer",
headers=biz_headers,
json={"tax_ids": [{"kind": "cnpj", "value": "11222333000181"},
{"kind": "cpf", "value": "529.982.247-25"}]},
)
resp = await client.patch(
"/api/invoices/issuer",
headers=biz_headers,
json={"tax_ids": [{"kind": "cnpj", "value": "11222333000181"}]},
)
assert [t["kind"] for t in resp.json()["tax_ids"]] == ["cnpj"]
async def test_omitting_tax_ids_leaves_them_untouched(
self, client: AsyncClient, biz_headers
):
await client.patch(
"/api/invoices/issuer",
headers=biz_headers,
json={"tax_ids": [{"kind": "cnpj", "value": "11222333000181"}]},
)
resp = await client.patch(
"/api/invoices/issuer", headers=biz_headers, json={"legal_name": "Alpha ME"}
)
assert len(resp.json()["tax_ids"]) == 1
async def test_a_workspace_with_no_identity_still_works(
self, client: AsyncClient, biz_headers
):
"""Nothing here is required until a document is rendered."""
resp = await client.get("/api/invoices/issuer", headers=biz_headers)
assert resp.status_code == 200
assert resp.json()["legal_name"] is None
assert resp.json()["tax_ids"] == []
async def test_a_personal_workspace_cannot_reach_the_issuer_routes(
self, client: AsyncClient, auth_headers, session: AsyncSession, test_user
):
from sqlalchemy import select
from app.models.workspace import Workspace, WorkspaceMember
result = await session.execute(
select(Workspace)
.join(WorkspaceMember, WorkspaceMember.workspace_id == Workspace.id)
.where(WorkspaceMember.user_id == test_user.id, Workspace.kind == "personal")
.limit(1)
)
personal = result.scalar_one()
headers = {**auth_headers, "X-Workspace-Id": str(personal.id)}
assert (await client.get("/api/invoices/issuer", headers=headers)).status_code == 404
assert (
await client.patch("/api/invoices/issuer", headers=headers, json={"legal_name": "x"})
).status_code == 404
# ---------------------------------------------------------------------------
# Page structure — the band layout and its pagination
# ---------------------------------------------------------------------------
def _doc(
n_lines: int,
footer_note: str = "Alpha ME",
n_installments: int = 0,
paid: str = "0",
deducted: str = "0",
):
"""A document with `n_lines` items, for exercising page breaks.
Built field by field rather than from a dict: keyword-splatting a
heterogeneous mapping loses every type on the way in, and this is the
one fixture the PDF tests all lean on.
"""
from app.services.invoice_document import (
DEFAULT_LABELS, DocumentInstallment, DocumentLine, DocumentParty, InvoiceDocument,
)
return InvoiceDocument(
number="FAT-7",
status="open",
state="open",
issue_date=date(2026, 8, 26),
due_date=date(2026, 9, 20),
currency="BRL",
subtotal=Decimal("1200"),
discount=Decimal("0"),
tax_total=Decimal("0"),
total=Decimal("1200"),
amount_paid=Decimal(paid),
amount_deducted=Decimal(deducted),
balance=Decimal("1200") - Decimal(paid) - Decimal(deducted),
issuer=DocumentParty(name="Alpha ME", tax_ids=[]),
client=DocumentParty(name="Beta LTDA", address=None, tax_ids=[]),
lines=[
DocumentLine(f"Item {i + 1}", Decimal("1"), Decimal("100"), Decimal("100"))
for i in range(n_lines)
],
labels=dict(DEFAULT_LABELS),
accent_color="#4f46e5",
logo_id=None,
payment_details="Pix: [email protected]",
notes="Obrigado.",
footer_note=footer_note,
custom_fields=[],
has_line_items=n_lines > 0,
installments=[
DocumentInstallment(f"Parcela {i + 1}", date(2026, 9, 20) + timedelta(days=30 * i), Decimal("10"))
for i in range(n_installments)
],
)
def _pages(document):
import io
import pypdf
return pypdf.PdfReader(io.BytesIO(invoice_pdf.render_pdf(document))).pages
def _lowest_text_y(page) -> float:
"""Where the lowest piece of text on the page sits, in points from
the bottom edge. Text drawn below zero is in the file and on no
page anyone will ever see; pypdf's plain extraction still finds it,
which is why the page-break tests cannot rely on text alone."""
ys: list[float] = []
def visit(text, cm, tm, font_dict, font_size):
if text.strip():
ys.append(tm[4] * cm[1] + tm[5] * cm[3] + cm[5])
page.extract_text(visitor_text=visit)
return min(ys)
def _text_y(page, needle: str) -> float:
"""The lowest baseline of the text containing `needle` on the page."""
ys: list[float] = []
def visit(text, cm, tm, font_dict, font_size):
if needle in text:
ys.append(tm[4] * cm[1] + tm[5] * cm[3] + cm[5])
page.extract_text(visitor_text=visit)
assert ys, f"{needle!r} not on the page"
return min(ys)
def _floor(document) -> float:
"""Where the body must stop: the footer band plus its breathing room."""
footer, closing = invoice_pdf._footer_flowables(document)
return invoice_pdf.MARGIN + invoice_pdf._footer_height(footer, closing) + invoice_pdf.FOOTER_GAP
class TestPageStructure:
def test_a_short_invoice_is_one_page(self):
assert len(_pages(_doc(3))) == 1
def test_a_long_invoice_paginates_instead_of_overflowing(self):
"""The regression this exists for.
The renderer used to draw one page and let anything taller run off
the bottom edge, where the line items were still in the file and
invisible to every human who opened it.
"""
pages = _pages(_doc(45))
assert len(pages) > 1
def test_no_line_item_is_lost_across_the_break(self):
n = 45
pages = _pages(_doc(n))
text = "\n".join(p.extract_text() for p in pages)
for i in range(n):
assert f"Item {i + 1}" in text, f"line {i + 1} vanished"
def test_every_page_identifies_the_document(self):
"""Someone holding page 3 has to know what it belongs to."""
for page in _pages(_doc(45)):
text = page.extract_text()
assert "FAT-7" in text
def test_the_payment_band_lands_on_the_last_page_only(self):
pages = _pages(_doc(45))
texts = [p.extract_text() for p in pages]
assert "Pix: [email protected]" in texts[-1]
for text in texts[:-1]:
assert "Pix: [email protected]" not in text
def test_totals_land_on_the_last_page_with_the_final_items(self):
texts = [p.extract_text() for p in _pages(_doc(45))]
assert "Item 45" in texts[-1]
assert "1,200.00" in texts[-1]
def test_a_deduction_is_on_the_page_so_the_totals_add_up(self):
"""Total 1,200, paid 1,000, balance 155: without its own row the
45 the client withheld is nowhere, and the page does not add up."""
text = _pages(_doc(3, paid="1000", deducted="45"))[0].extract_text()
assert "Deductions" in text and "BRL 45.00" in text
assert "BRL 1,000.00" in text and "BRL 155.00" in text
def test_settled_by_deduction_alone_still_shows_the_balance(self):
text = _pages(_doc(3, deducted="200"))[0].extract_text()
assert "Deductions" in text and "BRL 200.00" in text
assert "Paid" not in text
assert "BRL 1,000.00" in text
def test_an_untouched_invoice_shows_neither(self):
text = _pages(_doc(3))[0].extract_text()
assert "Deductions" not in text and "Balance due" not in text
def test_a_short_schedule_shares_page_one(self):
pages = _pages(_doc(3, n_installments=3))
assert len(pages) == 1
assert "Parcela 3" in pages[0].extract_text()
def test_a_long_schedule_paginates_and_loses_no_installment(self):
"""The schedule used to be drawn as part of the header, with no
page break: enough installments and the rows ran under the footer
and off the page, taking the line items with them."""
n = 80
pages = _pages(_doc(3, n_installments=n))
assert len(pages) > 1
text = "\n".join(p.extract_text() for p in pages)
for i in range(n):
assert f"Parcela {i + 1}" in text, f"installment {i + 1} vanished"
assert "Item 3" in text
assert "1,200.00" in pages[-1].extract_text()
for page in pages:
assert "FAT-7" in page.extract_text()
assert _lowest_text_y(page) > 0, "text drawn below the bottom edge"
def test_the_schedule_amount_header_sits_over_its_amounts(self):
"""Both AMOUNT headers are right-aligned like the figures under
them. The schedule's used to start at its column's left edge,
a quarter of the page away from the numbers it named."""
page = _pages(_doc(3, n_installments=2))[0]
xs: list[float] = []
def visit(text, cm, tm, font_dict, font_size):
if text.strip() == "AMOUNT":
xs.append(tm[4] * cm[0] + tm[5] * cm[2] + cm[4])
page.extract_text(visitor_text=visit)
assert len(xs) == 2
assert min(xs) > invoice_pdf.PAGE_WIDTH * 0.8
@pytest.mark.parametrize("n_lines", [39, 40, 61, 62])
def test_totals_never_sink_into_the_footer(self, n_lines):
"""Counts found by sweeping: the last chunk of the lines fit the
page on its own but not together with the totals, and the
renderer drew it anyway and put the totals over the footer."""
document = _doc(n_lines)
pages = _pages(document)
last = pages[-1]
assert f"Item {n_lines}" in last.extract_text()
assert _text_y(last, "1,200.00") >= _floor(document)
@pytest.mark.parametrize("n_installments", [25, 57, 59])
def test_a_schedule_with_no_lines_leaves_room_for_the_totals(self, n_installments):
document = _doc(0, n_installments=n_installments)
pages = _pages(document)
assert _text_y(pages[-1], "1,200.00") >= _floor(document)
for page in pages:
assert _lowest_text_y(page) > 0
def test_page_numbers_appear_only_when_there_is_more_than_one(self):
""""1 / 1" on a single-page invoice is noise that makes the
document look machine-made."""
single = _pages(_doc(3))[0].extract_text()
assert "/ 1" not in single
multi = _pages(_doc(45))
assert f"/ {len(multi)}" in multi[-1].extract_text()
def test_the_payment_band_sits_below_the_totals_on_the_page(self):
"""Position, not just presence: "how to pay me" halfway up an
otherwise empty page is the layout this replaced."""
import io
import pypdf
positions: dict[str, float] = {}
def visitor(text, _cm, tm, *_args):
stripped = text.strip()
for needle in ("Total", "PAYMENT DETAILS"):
if stripped.startswith(needle) and needle not in positions:
positions[needle] = tm[5]
page = pypdf.PdfReader(io.BytesIO(invoice_pdf.render_pdf(_doc(3)))).pages[0]
page.extract_text(visitor_text=visitor)
assert "Total" in positions and "PAYMENT DETAILS" in positions
# PDF y grows upward, so lower on the page is a smaller number.
assert positions["PAYMENT DETAILS"] < positions["Total"]
def test_an_invoice_with_no_lines_still_renders_the_bands(self):
page = _pages(_doc(0))[0].extract_text()
assert "Beta LTDA" in page
assert "Pix: [email protected]" in page
# ---------------------------------------------------------------------------
# Default labels follow the issuer, not the reader
# ---------------------------------------------------------------------------
class TestLabelPacks:
def test_a_shipped_language_gets_its_own_words(self):
from app.services.invoice_document import default_labels
assert default_labels("pt-BR")["invoice"] == "Fatura"
assert default_labels("de")["dueDate"] == "Fällig am"
assert default_labels("fr")["invoice"] == "Facture"
def test_regional_variants_share_a_pack(self):
"""`pt-BR` and `pt-PT` differ in ways a translator cares about and
not in the eighteen words on an invoice."""
from app.services.invoice_document import default_labels
assert default_labels("pt-PT") == default_labels("pt-BR")
def test_an_unshipped_language_falls_back_to_english(self):
from app.services.invoice_document import DEFAULT_LABELS, default_labels
assert default_labels("ja") == DEFAULT_LABELS
assert default_labels(None) == DEFAULT_LABELS
def test_every_pack_covers_every_label(self):
"""A half-translated document reads worse than an English one."""
from app.services.invoice_document import DEFAULT_LABELS, LABEL_PACKS
for language, pack in LABEL_PACKS.items():
assert set(pack) == set(DEFAULT_LABELS), language
@pytest.mark.asyncio
class TestIssuerLanguage:
async def test_a_brazilian_workspace_gets_a_portuguese_document(
self, client: AsyncClient, auth_headers
):
created = await client.post(
"/api/workspaces",
headers=auth_headers,
json={"name": "Consultoria BR", "kind": "business",
"self_membership": True, "locale": "pt-BR"},
)
assert created.status_code == 201, created.text
headers = {**auth_headers, "X-Workspace-Id": created.json()["id"]}
invoice = await make_invoice(client, headers)
doc = (
await client.get(f"/api/invoices/{invoice['id']}/document", headers=headers)
).json()
assert doc["labels"]["invoice"] == "Fatura"
assert doc["labels"]["billTo"] == "Cliente"
async def test_an_explicit_label_still_wins_over_the_pack(
self, client: AsyncClient, auth_headers
):
created = await client.post(
"/api/workspaces",
headers=auth_headers,
json={"name": "Consultoria BR2", "kind": "business",
"self_membership": True, "locale": "pt-BR"},
)
headers = {**auth_headers, "X-Workspace-Id": created.json()["id"]}
await client.patch(
"/api/invoices/settings",
headers=headers,
json={"template": {"labels": {"invoice": "Recibo"}}},
)
invoice = await make_invoice(client, headers)
doc = (
await client.get(f"/api/invoices/{invoice['id']}/document", headers=headers)
).json()
assert doc["labels"]["invoice"] == "Recibo"
# Untouched labels still come from the pack, not from English.
assert doc["labels"]["dueDate"] == "Vencimento"
async def test_switching_the_interface_never_retitles_an_issued_document(
self, client: AsyncClient, auth_headers
):
"""The words were the sender's choice at issuance. Changing the
workspace language afterwards must not rewrite a document the
client already holds."""
created = await client.post(
"/api/workspaces",
headers=auth_headers,
json={"name": "Consultoria BR3", "kind": "business",
"self_membership": True, "locale": "pt-BR"},
)
workspace_id = created.json()["id"]
headers = {**auth_headers, "X-Workspace-Id": workspace_id}
invoice = await make_invoice(client, headers)
await client.patch(
f"/api/workspaces/{workspace_id}", headers=headers, json={"locale": "en"}
)
doc = (
await client.get(f"/api/invoices/{invoice['id']}/document", headers=headers)
).json()
assert doc["labels"]["invoice"] == "Fatura"
@pytest.mark.asyncio
async def test_an_imported_number_is_rendered_with_the_source_prefix(
client: AsyncClient, biz_headers
):
"""Our prefix belongs on our paper. A supplier reference of FAT-9931
must not come back as INV-9931 because that is what we call ours."""
await client.patch(
"/api/invoices/settings", headers=biz_headers, json={"number_prefix": "INV-"}
)
imported = await make_invoice(
client, biz_headers, origin="imported",
external_source="erp", external_id="FAT-9931", external_number="FAT-9931",
)
doc = await client.get(f"/api/invoices/{imported['id']}/document", headers=biz_headers)
assert doc.json()["number"] == "FAT-9931"
bare = await make_invoice(
client, biz_headers, origin="imported",
external_source="erp", external_id="7",
)
doc = await client.get(f"/api/invoices/{bare['id']}/document", headers=biz_headers)
assert doc.json()["number"] is None
ours = await make_invoice(client, biz_headers)
doc = await client.get(f"/api/invoices/{ours['id']}/document", headers=biz_headers)
assert doc.json()["number"] == "INV-1"
@pytest.mark.asyncio
async def test_our_identity_stays_off_a_supplier_document(client: AsyncClient, biz_headers):
"""Our bank details under "pay to" on a bill we owe state the opposite
of what is true, and our logo brands a page we did not write."""
await client.patch(
"/api/invoices/settings",
headers=biz_headers,
json={
"payment_details": "Banco 001 · Ag 1234 · CC 56789-0",
"footer_note": "Obrigado pela preferencia!",
"accent_color": "#FF0000",
},
)
# The logo arrives as a file now, on its own route.
logo_id = (await _put_logo(client, biz_headers)).json()["logo_id"]
bill = await make_invoice(
client, biz_headers, direction="payable", origin="imported",
external_source="erp", external_id="FAT-1",
)
doc = (
await client.get(f"/api/invoices/{bill['id']}/document", headers=biz_headers)
).json()
assert doc["logo_id"] is None
assert doc["payment_details"] is None
assert doc["footer_note"] is None
assert doc["accent_color"] != "#FF0000"
# On our own invoice every one of them is still printed.
ours = await make_invoice(client, biz_headers)
doc = (
await client.get(f"/api/invoices/{ours['id']}/document", headers=biz_headers)
).json()
assert doc["logo_id"] == logo_id
assert doc["payment_details"] == "Banco 001 \u00b7 Ag 1234 \u00b7 CC 56789-0"
assert doc["footer_note"] == "Obrigado pela preferencia!"
assert doc["accent_color"] == "#FF0000"
# ---------------------------------------------------------------------------
# The logo is a file this workspace owns
# ---------------------------------------------------------------------------
def _png(width: int = 40, height: int = 20, colour: tuple = (79, 70, 229)) -> bytes:
import io as _io
from PIL import Image as _Image
buf = _io.BytesIO()
_Image.new("RGB", (width, height), colour).save(buf, format="PNG")
return buf.getvalue()
async def _put_logo(client, headers, data=None, content_type="image/png", name="logo.png"):
return await client.post(
"/api/invoices/settings/logo",
headers=headers,
files={"file": (name, data if data is not None else _png(), content_type)},
)
@pytest.mark.asyncio
async def test_an_uploaded_logo_reaches_the_pdf(client: AsyncClient, biz_headers):
"""It never did: `render_pdf` took logo bytes and no caller passed
any, so a workspace saw its mark on screen and got a file without."""
resp = await _put_logo(client, biz_headers)
assert resp.status_code == 200, resp.text
assert resp.json()["logo_id"]
invoice = await make_invoice(client, biz_headers)
pdf = await client.get(f"/api/invoices/{invoice['id']}/pdf", headers=biz_headers)
import io as _io
import pypdf as _pypdf
reader = _pypdf.PdfReader(_io.BytesIO(pdf.content))
assert len(list(reader.pages[0].images)) == 1
@pytest.mark.asyncio
async def test_replacing_the_logo_leaves_issued_documents_alone(
client: AsyncClient, biz_headers
):
"""The freeze rule, applied to a file. An invoice a client is holding
does not change its letterhead because the issuer rebranded."""
first = (await _put_logo(client, biz_headers)).json()["logo_id"]
invoice = await make_invoice(client, biz_headers)
second = (await _put_logo(client, biz_headers, data=_png(colour=(200, 30, 30)))).json()[
"logo_id"
]
assert second != first
doc = await client.get(f"/api/invoices/{invoice['id']}/document", headers=biz_headers)
assert doc.json()["logo_url"] == f"/api/invoices/logo/{first}"
# And the old file is still there to serve, because the document
# still points at it.
served = await client.get(f"/api/invoices/logo/{first}", headers=biz_headers)
assert served.status_code == 200
assert served.headers["content-type"] == "image/png"
@pytest.mark.asyncio
async def test_whatever_arrives_is_stored_as_a_bounded_png(
client: AsyncClient, biz_headers
):
"""Re-encoding fixes the content type the route answers with, bounds
the size every PDF carries, and drops the metadata a photo brings."""
import io as _io
from PIL import Image as _Image
buf = _io.BytesIO()
_Image.new("RGB", (3000, 1200), (10, 200, 90)).save(buf, format="JPEG")
resp = await _put_logo(
client, biz_headers, data=buf.getvalue(), content_type="image/jpeg", name="mark.jpg"
)
logo_id = resp.json()["logo_id"]
served = await client.get(f"/api/invoices/logo/{logo_id}", headers=biz_headers)
assert served.headers["content-type"] == "image/png"
stored = _Image.open(_io.BytesIO(served.content))
assert stored.format == "PNG"
assert max(stored.size) <= 600
@pytest.mark.asyncio
async def test_a_file_that_is_not_an_image_is_refused(client: AsyncClient, biz_headers):
resp = await _put_logo(
client, biz_headers, data=b"%PDF-1.4 not an image", content_type="application/pdf",
name="nope.pdf",
)
assert resp.status_code == 400
@pytest.mark.asyncio
async def test_removing_the_logo_leaves_documents_that_used_it(
client: AsyncClient, biz_headers
):
logo_id = (await _put_logo(client, biz_headers)).json()["logo_id"]
invoice = await make_invoice(client, biz_headers)
cleared = await client.delete("/api/invoices/settings/logo", headers=biz_headers)
assert cleared.json()["logo_id"] is None
# The invoice issued under it still draws it.
doc = await client.get(f"/api/invoices/{invoice['id']}/document", headers=biz_headers)
assert doc.json()["logo_url"] == f"/api/invoices/logo/{logo_id}"
@pytest.mark.asyncio
async def test_the_shared_page_serves_the_logo_through_its_token(
client: AsyncClient, biz_headers
):
"""The client opening a link has no session, so the mark has to be
reachable by the token and by nothing else."""
await _put_logo(client, biz_headers)
invoice = await make_invoice(client, biz_headers)
token = (
await client.post(f"/api/invoices/{invoice['id']}/share", headers=biz_headers)
).json()["token"]
shared = await client.get(f"/api/public/invoices/{token}")
assert shared.json()["logo_url"] == f"/api/public/invoices/{token}/logo"
# The workspace's internal handle for the file is not in the response.
assert "logo_id" not in shared.json()
served = await client.get(f"/api/public/invoices/{token}/logo")
assert served.status_code == 200
assert served.headers["content-type"] == "image/png"
@pytest.mark.asyncio
async def test_a_unit_is_printed_beside_the_quantity(client: AsyncClient, biz_headers):
""""32 hours x 180.00" is a claim the payer can check. "32 x 180.00"
is one they have to take on trust."""
invoice = await make_invoice(
client, biz_headers,
lines=[{"description": "Desenvolvimento", "quantity": "32", "unit": "horas",
"unit_price": "180.00"}],
total="5760.00",
)
doc = (
await client.get(f"/api/invoices/{invoice['id']}/document", headers=biz_headers)
).json()
assert doc["lines"][0]["unit"] == "horas"
import io as _io
import pypdf as _pypdf
pdf = await client.get(f"/api/invoices/{invoice['id']}/pdf", headers=biz_headers)
text = _pypdf.PdfReader(_io.BytesIO(pdf.content)).pages[0].extract_text()
assert "32 horas" in text
@pytest.mark.asyncio
async def test_a_line_without_a_unit_reads_as_it_always_did(
client: AsyncClient, biz_headers
):
"""Optional means optional: nothing is invented for a line that
counts nothing in particular."""
invoice = await make_invoice(
client, biz_headers,
lines=[{"description": "Projeto fechado", "quantity": "1", "unit_price": "900.00"}],
total="900.00",
)
doc = (
await client.get(f"/api/invoices/{invoice['id']}/document", headers=biz_headers)
).json()
assert doc["lines"][0]["unit"] is None
@pytest.mark.asyncio
async def test_a_client_name_with_markup_survives_the_pdf(
client: AsyncClient, biz_headers, session: AsyncSession, business_ws, test_user
):
"""ReportLab reads its argument as markup, so an unescaped `<Ltda>`
was swallowed as an unknown tag: the client's name went out on the
document truncated, with nothing to notice it by."""
payee = Payee(
id=uuid.uuid4(),
user_id=test_user.id,
workspace_id=uuid.UUID(business_ws["id"]),
name="Alpha & Beta <Ltda>",
)
session.add(payee)
await session.commit()
invoice = await make_invoice(
client, biz_headers, payee_id=str(payee.id),
lines=[{"description": "R&D <phase 1>", "quantity": "1", "unit_price": "100.00"}],
)
pdf = await client.get(f"/api/invoices/{invoice['id']}/pdf", headers=biz_headers)
assert pdf.status_code == 200
import io as _io
import pypdf as _pypdf
text = _pypdf.PdfReader(_io.BytesIO(pdf.content)).pages[0].extract_text()
assert "Alpha & Beta <Ltda>" in text
assert "R&D <phase 1>" in text
def test_an_oversized_raster_is_refused_before_it_is_decoded():
"""A 10,000 x 10,000 PNG of flat colour is a few hundred kilobytes and
asks for hundreds of megabytes to decode. Every size limit above lets
it through, and `thumbnail` only shrinks it long afterwards."""
import io as _io
from PIL import Image as _Image
from app.services import invoice_logo_service
buf = _io.BytesIO()
_Image.new("RGB", (10000, 10000), (255, 0, 0)).save(buf, format="PNG")
assert len(buf.getvalue()) < 1_000_000, "the point is that it is small"
with pytest.warns(_Image.DecompressionBombWarning, match="Image size"), \
pytest.raises(ValueError, match="megapixels"):
invoice_logo_service.normalise(buf.getvalue(), "image/png")
def test_a_line_taller_than_a_page_still_finishes():
"""It used to hang, not fail. `split` returned nothing for a row
taller than the space, the loop asked for a fresh page, failed again
on the empty page and asked again — holding the worker until
something killed it, which is worse than an error the caller can see.
Guarded twice: the table may now break inside a row, and a failure to
split on an already-empty page draws the content instead of asking
for one more."""
import signal
huge = ("Servico de consultoria detalhado " * 400).strip()
def give_up(signum, frame):
raise AssertionError("pagination did not terminate")
signal.signal(signal.SIGALRM, give_up)
signal.alarm(20)
try:
document = _doc(1)
document.lines[0].description = huge
pdf = invoice_pdf.render_pdf(document)
finally:
signal.alarm(0)
import io as _io
import pypdf as _pypdf
assert pdf.startswith(b"%PDF")
assert len(_pypdf.PdfReader(_io.BytesIO(pdf)).pages) >= 1