Hacktoberfest 2026: le issue che i maintainer hanno segnato per ottobre, aperte e adatte ai principianti. Sfoglia le issue Hacktoberfest

Stop asserting exception messages in PHP tests: define a convention (error codes or typed exceptions)

Aperta
  • Qualcosa non va?
#8,117 11 commenti 0 reazioni 0 assegnatari Vedi su GitHub

I maintainer di solito rispondono entro 1 giorno

Nessuno ha ancora preso questa issue.

Valutazione

Difficoltà
5/5
Tempo stimato
Più di una settimana
Idoneità per principianti
35/100
Tipo di issue
Refactoring
Chiarezza
Abbastanza chiara
Stato di attività
Attiva
Stack tecnologico
php
Ambito
backend-api-design, testing

Direzione di ricerca

Inizia dalla discussione in #8092, poi esamina le sottoclassi delle eccezioni in lib/Exception/, le asserzioni dei messaggi nei file di test PHP e la gestione del codice in ErrorPayloadBuilder e SignFileService. Documenta innanzitutto una convenzione per i codici di errore o le eccezioni tipizzate, inclusi i codici esistenti; il lavoro sarà considerato completato quando la decisione consentirà PR piccole con coppie source/test senza modificare i messaggi visibili all’utente o il comportamento dell’API.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Descrizione

good first issue php technical debt

Follow-up of the discussion in #8092 (https://github.com/LibreSign/libresign/pull/8092#discussion_r3883064993).

Many PHP tests assert exceptions by matching their message. When the message is translatable or just easy to change, editing the text in lib/ silently requires editing the test too, and whoever changes the text (not necessarily a developer) has to know that. The suggestion in #8092 was to assert the error code or the exception class instead of the text.

Current state

Numbers from main today:

  • expectExceptionMessage(): 174 calls in 52 test files (plus 13 expectExceptionMessageMatches()).
  • expectExceptionCode(): 12 calls in 9 files.
  • throw new LibresignException(...): 287 places. 161 of them use a translated message ($l10n->t(...)), 126 use a literal string.
  • Only 51 of the 287 carry a code, and the values mix conventions: 1 (22), 422 (11), 404 (7), 500 (4), 400 (3), Http::STATUS_UNPROCESSABLE_ENTITY (3) and Http::STATUS_FORBIDDEN (1). LibresignException itself defines no code constants, and the code is exposed to clients through ErrorPayloadBuilder (code) and SignFileService (error_code), so any convention also touches the API contract.
  • 8 test files assert a translated message while building the real IL10N from the factory, so they depend on the test locale.
  • There are already typed subclasses in lib/Exception/ (InvalidPasswordException, InvalidSignatureException, EmptyCertificateException, ...), but most throw sites still use the base LibresignException.

What should be decided first

Two directions came up in #8092. They are not exclusive, but a convention is needed before touching many files:

  1. Error codes: define constants for the codes (a dedicated class, like JSActions, following the "HTTP-like plus one digit" idea to avoid confusion with HTTP status codes), use them at the throw sites, and assert them with expectExceptionCode().
  2. Typed exceptions: extend the existing lib/Exception/ subclasses so tests assert the class with expectException().

Please use this issue to settle the convention (and decide what to do with the existing 1/4xx codes), then the work can be split into small PRs.

How to contribute

[!IMPORTANT]
Do not solve this issue in one PR.

Like #8053, each PR should cover one or two related source/test pairs, reference this issue without Fixes/Closes, and keep the diff small. Please comment here with the files you want to work on before starting.

Suggested order:

  1. Tests that assert translated messages ($l10n->t(...) in lib/, real IL10N in the test), because they break on any wording change.
  2. Tests that assert literal messages in business rules (signing, certificates, policies, permissions, validation, identity flows).
  3. The remaining message assertions.

Do not change production behavior (messages shown to users, API payloads) only to make a test easier; when a code or a class is added, keep the message as is.

Effort

The complete issue is medium-to-high effort because it covers many files, but each PR should be low effort.

Lingua principale
PHP
Stelle
828
Fork
157
Merge medio
6h 48m
PR unite (30g)
622

Preparare l'ambiente

Apri in Codespaces

Avvia il container di sviluppo del progetto nel browser, con il tuo account GitHub.

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di LibreSign/libresign

Tutte le issue di LibreSign/libresign

Issue simili

Altre issue su PHP

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.