Les proves et diuen que alguna cosa està trencada. Gairebé mai no et diuen per què. Una prova d'integració que esperava 201 i ha rebut 500 t'ha fet un favor enorme —ha detectat la fallada abans que un client—, però ara cal esbrinar què ha passat dins d'aquella petició: en quin middleware, amb quines dades, en quina línia.

Aquesta lliçó tanca el mòdul amb l'altra meitat de l'ofici: les eines i el mètode per diagnosticar. Una frontera abans de començar, perquè no hi hagi confusió: aquí diagnostiquem el que falla. Mesurar i optimitzar el que funciona però va lent —perfils de CPU, flamegraphs, proves de càrrega— és el mòdul 10.

1. Del console.log al depurador
2. El depurador integrat: --inspect
3. Depurar des de VS Code, incloses les proves de Mocha
4. Punts d'interrupció i execució pas a pas
5. Depurar codi asíncron
6. Llegir una traça d'error de veritat
7. Errors freqüents i el seu diagnòstic
8. Fuites de memòria
9. Depurar en producció sense aturar el servei
10. Mètode de depuració

Comencem per l'obvi: console.log no és cap vergonya. És instantani, funciona en qualsevol entorn, no requereix configuració i moltes vegades resol el problema en trenta segons. El que sí que és cert és que obliga a modificar el codi, a reiniciar, a endevinar per endavant què imprimir, i amb objectes imbricats imprimeix [Object] justament on hi havia la resposta. Aprofita primer tot el que la consola ofereix més enllà de log:

console.dir(objecte, { depth: null }) és probablement el truc més rendible de la llista: per defecte Node només imprimeix dos nivells d'imbricació, i amb una comanda que conté línies que contenen entrades aquests dos nivells s'exhaureixen de seguida.

Tot i així, el depurador dona tres coses que la consola no pot donar:

Node porta un depurador incorporat que parla el protocol de Chrome DevTools, i s'activa amb dos indicadors:

La diferència és decisiva. --inspect serveix per depurar una cosa que passa més tard —una petició HTTP concreta, un esdeveniment—: el servidor arrenca i espera. --inspect-brk serveix per depurar l'arrencada: la lectura de la configuració, la connexió a la base de dades, el muntatge dels middlewares; sense -brk, tot això ja ha passat abans que tinguis temps de connectar-t'hi.

Per connectar-t'hi des de Chrome o Edge, obre chrome://inspect, busca el teu procés a «Remote Target» i prem inspect: s'obre DevTools amb la pestanya Sources, on pots posar punts d'interrupció, i amb la pestanya Memory, que farem servir per a les fuites. Existeix també un depurador de línia d'ordres, node inspect src/servidor.js, útil per SSH on no hi ha navegador: c continua, n avança una línia, s entra a la funció, o en surt, repl avalua expressions. És auster, però un dia en un servidor remot et salvarà la tarda.

Aquesta és la manera més productiva en el dia a dia. A .vscode/launch.json:

La segona configuració —obres comandes.test.js, hi poses un punt d'interrupció i prems F5— és la més usada de totes; n'hi ha prou de duplicar-la sense ${relativeFile} per depurar la bateria completa. La tercera serveix quan el procés ja s'executa amb --inspect, per exemple dins d'un contenidor.

Tres detalls marquen la diferència. "--timeout", "0" és imprescindible a les configuracions de Mocha: sense ell, Mocha avorta la prova als 5000 ms mentre tu estàs aturat llegint variables. skipFiles amb node_modules i <node_internals> evita que el pas a pas et fiqui dins d'Express o de Mongoose, de manera que en «entrar a la funció» entris al teu codi. I envFile apuntant a .env.test garanteix que depures contra la base de proves i no contra la de desenvolupament.

Depurar les proves és, de bon tros, el cas més útil: tens una fallada reproduïble de manera determinista, aïllada, amb dades conegudes, i la pots aturar on vulguis. És la situació ideal per depurar, i és un regal que t'ha fet la resta del mòdul.

Hi ha tres tipus de punt d'interrupció, i només se'n fa servir el primer. El normal atura sempre en aquella línia. El condicional atura només si es compleix una expressió, i és l'eina que converteix una tarda en cinc minuts: amb la condició sessio.id === 'ses-001-1' && quantitat > 4, en un bucle sobre 7 sessions i 1811 vendes atures exactament al cas que investigues (les seves variants són el comptador d'encerts, que atura a la crida número 50, i l'expressió de registre). El de registre (logpoint) no atura res: imprimeix un missatge amb interpolació, Venent {quantitat} de {sessio.id}, en queden {sessio.lliures}, cada vegada que hi passa. És un console.log que no toca el codi font, perfecte quan el problema només apareix sota concurrència i aturar l'execució el faria desaparèixer.

Els controls són continuar (F5, segueix fins al pròxim punt), passar per sobre (F10, executa la línia sense entrar a les funcions que cridi), entrar (F11) i sortir (Shift+F11, acaba la funció actual i torna a qui l'ha cridat).

I els quatre panells: Variables mostra l'àmbit local, el de tancament i el global al punt on estàs aturat, i és on descobreixes que req.body és undefined; Inspecció segueix expressions concretes a cada pas (sessio.lliures, req.usuari.rol); Pila de crides reconstrueix com s'ha arribat fins aquí i hi pots fer clic a qualsevol marc per veure'n les variables, que sol ser on és la fallada real; i la Consola de depuració avalua qualsevol expressió en el context actual.

Aquesta última línia és una capacitat enorme: comprovar una hipòtesi sense editar, desar i reiniciar.

A Node, la meitat dels problemes passen després d'un await, i allà la depuració té una peculiaritat. La pila es trenca perquè quan registres un callback amb setTimeout o resols una promesa, la funció s'executa més tard, en un altre torn del bucle d'esdeveniments, i aleshores la pila original ja s'ha desmuntat. Per això una traça clàssica mostra tres marcs (Timeout._onTimeout, listOnTimeout, processTimers), cap d'útil: no diu qui va programar aquell timeout.

Les traces asíncrones són la solució. Node manté informació que permet reconstruir la cadena lògica a través dels await, i DevTools i VS Code la mostren amb separadors:

Els marcadors --- await --- separen els trams asíncrons i es llegeixen de dalt a baix com a passat cap enrere: l'error s'ha llançat a vendre, cridada des de comprarEntrades, que va ser esperada des de crearComanda.

Quatre consells pràctics. async/await produeix traces molt millors que els callbacks imbricats, una raó més per preferir-lo. No facis servir mai catch buits: esborren l'única pista que tenies. Preserva la causa en reembolcallar un error, que és el que fa útil una jerarquia com la nostra. I captura els rebuigs no gestionats a l'arrencada perquè no es perdin mai en silenci:

Una traça real és plena de soroll. En dissecarem una:

Es llegeix en aquest ordre. El tipus i el missatge primer: un ValidationError de Mongoose amb el camp exacte (linies.0.quantitat), el valor rebut (7) i la regla violada (màxim 6); el 80 % de les vegades la primera línia ja ho diu tot. Després salta el soroll de node_modules i node:internal, perquè no arreglaràs Mongoose. Tot seguit busca el primer marc de /app/src/ comptant des de dalt —repositoris/comandes.js:47—, que és on el teu codi ha provocat l'error, i continua baixant pels teus marcs per reconstruir el camí: repositori ← servei ← controlador. Diagnòstic: algú ha demanat 7 entrades i la validació de zod no l'ha aturat abans d'arribar al model, així que la fallada real no és de Mongoose sinó un forat a la validació d'entrada, i probablement el client rebi un 500 en comptes del 422 que li correspon.

Dues eines per controlar les traces. Node desa 10 marcs per defecte, curt per a cadenes asíncrones llargues: s'amplia amb node --stack-trace-limit=50 o amb Error.stackTraceLimit = 50. I Error.captureStackTrace(this, this.constructor) al constructor d'ErrorDAplicacio elimina de la traça els marcs del mateix constructor, un detall petit que fa que els teus errors assenyalin directament el codi que els ha llançat.

Tots aquests ja han aparegut al llarg del curs. Aquesta taula és la teva referència de consulta:

Els dos últims mereixen desenvolupament. Amb "exit": false al .mocharc.json, el procés que no acaba apareix tan bon punt t'oblides de tancar alguna cosa:

Imprimeix cada handle i request obert amb la traça del lloc on es va crear, i sol ser una de tres coses: la connexió de Mongoose, un setInterval d'una memòria cau o d'un netejador de tokens, o un http.Server creat a mà. L'alternativa sense instal·lar res és imprimir process._getActiveHandles().length en un after: és API interna i sense documentar, però per depurar serveix.

Per a la petició penjada, el diagnòstic més ràpid és un middleware temporal de traçat, app.use(tracar('json')), app.use(tracar('autenticar')), etcètera, on tracar(etiqueta) imprimeix [${req.idPeticio}] passa per ${etiqueta} i crida next(). L'últim tracar que apareix a la consola assenyala el middleware següent com a culpable.

Una fuita és memòria que es reté i ja no es fa servir. En un script no importa; en un servidor que corre setmanes, acaba en un reinici per falta de memòria. Els símptomes: la memòria del procés creix de manera sostinguda i no baixa després de les hores vall, el rendiment es degrada a poc a poc perquè el recol·lector treballa cada vegada més, i finalment arriba JavaScript heap out of memory.

El primer diagnòstic no necessita eines: un setInterval temporal que imprimeixi process.memoryUsage() cada minut. Dels seus quatre camps, rss és la memòria total del procés, heapTotal el que ha reservat V8, external els Buffers, i heapUsed és el que importa. La clau no és el valor absolut sinó la tendència durant hores: que pugi i baixi és normal, que només pugi no ho és.

El diagnòstic seriós és comparar dues instantànies del munt. Arrenca amb node --inspect, ves a chrome://inspect, pestanya Memory, i pren la instantània A. Exercita l'aplicació repetint diverses vegades el mateix cicle —compres, llistats, entrades de sessió— i pren la instantània B. Selecciona B i canvia la vista a Comparison contra A: la columna Delta mostra quins tipus d'objecte han crescut sense alliberar-se, i si després de deu cicles idèntics veus 10.000 objectes Sessio més o 500 oients més, allà hi ha la teva fuita. La secció Retainers et diu qui manté viva la referència, que és la informació que realment necessites. També la pots generar des del codi amb v8.writeHeapSnapshot(), útil en un servidor sense navegador: retorna la ruta d'un fitxer .heapsnapshot que després es descarrega i es carrega a DevTools.

Les causes típiques, totes ja vistes en aquest curs:

L'avís MaxListenersExceededWarning: Possible EventEmitter memory leak detected. 11 venda-registrada listeners added és un regal de Node: t'està dient exactament on has de mirar. No el silenciïs apujant setMaxListeners; investiga per què s'afegeixen.

En producció no pots posar un punt d'interrupció: aturaries les peticions de tots els usuaris. Les tècniques són unes altres.

1. Registres estructurats amb identificador de petició. És, de bon tros, l'eina més valuosa. El middleware id-peticio.js del mòdul 6 assigna un identificador únic a cada petició i registre-peticions.js l'inclou a cada línia:

Amb aquest idPeticio reconstrueixes el recorregut complet d'una petició concreta entre milers de línies simultànies: quan la Lucía escrigui dient que no ha pogut comprar a les 18:22, tens la seva història sencera filtrant per un camp. El monitoratge i l'agregació d'aquests registres es tanquen al mòdul 11. Regla d'or: no registris mai dades personals, contrasenyes, tokens ni capçaleres Authorization, perquè un registre és un fitxer que moltes persones poden llegir i que sovint s'envia a un tercer.

2. Activar l'inspector amb un senyal, temporalment. kill -USR1 <pid> fa que Node obri l'inspector al 9229 sense reiniciar el procés, i t'hi connectes per un túnel SSH: ssh -L 9229:localhost:9229 usuari@servidor, i després chrome://inspect a la teva màquina local veu el procés remot.

3. No deixis mai --inspect obert en un servidor públic. Això és un advertiment de seguretat seriós, no una recomanació d'estil: el port de l'inspector no té autenticació, així que qualsevol que hi arribi pot avaluar codi arbitrari al teu procés, llegir memòria —inclosos els secrets JWT i les contrasenyes de la base de dades— i modificar el comportament en viu. És execució remota de codi servida en safata. Les regles mínimes: mai --inspect=0.0.0.0:9229 (per defecte escolta només a 127.0.0.1, deixa-ho així), accedeix-hi sempre per túnel SSH, tanca'l tan bon punt acabis, i que el tallafoc bloquegi el 9229 des de l'exterior com a xarxa de seguretat.

4. Bolcats de memòria sota demanda, mitjançant un punt d'entrada intern protegit per rol d'administrador i accessible només des de la xarxa privada que cridi v8.writeHeapSnapshot(). Permet investigar una fuita en producció sense tocar el servei.

Convé deixar clara la frontera, perquè la confusió és habitual:

Les eines sense mètode produeixen tardes perdudes. Aquest és el procediment, en ordre.

1. Reproduir. Una fallada que no pots reproduir no la pots arreglar; com a molt pots canviar coses fins que sembli que desapareix. Reuneix petició exacta, usuari i rol, dades implicades, hora i idPeticio; si és intermitent, executa-la en bucle fins que caigui.

2. Aïllar. Redueix fins al mínim que continua fallant: falla sense autenticació?, amb una altra sessió?, només amb evt-002? Cada resposta elimina mig bosc.

3. Formular una hipòtesi falsable. No «alguna cosa estranya passa amb l'aforament», sinó «crec que vendre() compara amb < en lloc de <= i per això rebutja l'última entrada». Una hipòtesi que no es pot refutar no serveix de res.

4. Comprovar-la amb un punt d'interrupció, un punt de registre o una consulta. Si era falsa, no la retorcis: formula'n una altra. Aferrar-se a una hipòtesi equivocada és la causa número u de les depuracions llargues.

5. Bisecció amb git bisect quan sàpigues que abans funcionava:

Amb 1000 commits entre el bo i el dolent, git bisect troba el culpable en 10 passos, i amb run te'n vas a fer un cafè i tornes amb el commit exacte. Fixa't en el que implica: git bisect automàtic només funciona si tens proves. És un altre benefici d'aquest mòdul que no es veu fins que el necessites.

6. Escriure una prova que reprodueixi la fallada, abans d'arreglar-la. Aquest pas tanca el cercle del mòdul sencer i és innegociable. L'ordre importa: escrius la prova i ha de fallar —si passa, no has entès la fallada i estàs a punt d'arreglar una altra cosa—, després arregles el codi, la prova passa, i per últim executes la bateria completa per comprovar que l'arranjament no ha trencat res més.

Tres coses guanyes amb aquesta prova: demostres que has entès la fallada, garanteixes que no tornarà mai i deixes documentat un cas límit que a ningú no se li havia acudit. Una fallada en producció és cara; malbaratar-la sense convertir-la en una prova és llençar els diners.

• Depurar sense reproduir. Canviar codi fins que «sembla que ja va» no arregla res: ho amaga fins al pitjor moment possible.
• Oblidar --timeout 0 en depurar proves. Mocha avorta la prova mentre estàs aturat llegint variables i et penses que el depurador està trencat.
• No fer servir skipFiles. Prems F11 i acabes dins d'express/lib/router/layer.js sense saber com sortir-ne.
• catch buits. Esborren l'única informació que tenies; registra sempre, encara que sigui en nivell debug.
• Perdre la causa en reembolcallar errors. Fes servir { cause: error }: la traça original val més que un missatge bonic.
• Silenciar MaxListenersExceededWarning. És un detector de fuites gratuït; apujar el límit és tapar l'avís d'incendi.
• Deixar --inspect en un servidor accessible. És execució remota de codi sense autenticació. Túnel SSH sempre.
• Registrar tokens o contrasenyes. Un registre és un fitxer que molta gent llegeix i que sol sortir de la teva infraestructura.
• Consell: quan una prova d'integració falli amb 500, imprimeix resposta.body i busca l'idPeticio a la sortida del servidor: tens la història completa en dos passos. I aprèn bé els punts d'interrupció condicionals, que és l'habilitat que més temps estalvia de tota la lliçó.

Per a cada símptoma, indica la causa més probable, l'eina amb què ho confirmaries i l'arranjament:

1. npm test imprimeix 74 passing i el procés es queda penjat sense tornar l'indicador.
2. POST /api/comandes respon 500 amb Cannot set headers after they are sent to the client.
3. GET /api/esdeveniments/hola retorna 500 en lloc de 404.
4. El servidor fa cinc dies que està amunt i heapUsed ha passat de 90 MB a 780 MB.
5. Una prova d'integració passa sola i falla dins de la bateria completa.

Agafa la prova de concurrència de 09-04. Configura .vscode/launch.json amb l'entrada «Mocha: el fitxer obert», col·loca un punt d'interrupció condicional dins del repositori de comandes que només s'activi quan lliures < 2, i descriu què veuries al panell de pila de crides i al de variables. Explica per què --timeout 0 és imprescindible aquí.

Un organitzador de la Sala Bóveda informa que l'informe d'evt-002 mostra ingressosCentims: NaN des d'ahir. Dissenya el procés complet: com reproduir-ho, com aïllar-ho, dues hipòtesis falsables, com faries servir git bisect, i escriu la prova que reprodueix la fallada (ha de fallar abans de l'arranjament).

Exercici 1. (1) Un handle obert, gairebé segur la connexió a Mongo sense tancar; confirma-ho amb why-is-node-running a l'afterAll i arregla-ho amb await desconnectar() al ganxo arrel. (2) Doble resposta: un gestor fa res.json(...) i després crida next(error), o hi ha un await després de respondre que llança; punt d'interrupció al gestorDErrors i mira la pila; l'arranjament és return res.json(...). (3) CastError de Mongoose: hola no és un ObjectId vàlid i l'error arriba com a desconegut, que ESTAT_PER_CODI tradueix a 500; valida el paràmetre amb zod o tradueix CastError a RecursNoTrobat al repositori. (4) Fuita de memòria: dues instantànies del munt comparades després de cicles idèntics, amb els oients acumulats a GestorDeVendes i la memòria cau sense límit de canvi-divises.js com a principals sospitosos. (5) Contaminació entre proves: un stub sense restaurar, un rellotge fals viu o dades que una altra prova ha deixat; confirma-ho executant la bateria en ordre invers i arregla-ho amb sinon.restore() al ganxo arrel i neteja a l'afterEach.

Exercici 2. El punt d'interrupció condicional es col·loca a la línia del repositori on es comprova l'aforament, amb la condició sessio.lliures < 2. Al panell de pila de crides veuries, de dalt a baix, el mètode del repositori, comprarEntrades, el controlador crearComanda i diversos marcs d'Express separats per marcadors --- await ---; fent clic al marc del controlador veuries req.usuari i req.dadesValidades d'aquella petició concreta. Al panell de variables veuries sessio.lliures amb el valor exacte a l'instant en què una de les deu compres simultànies troba l'aforament gairebé exhaurit, i podries comprovar a la consola si la comparació amb quantitat dona el que esperaves.

--timeout 0 és imprescindible per una raó específica: la prova llança deu peticions amb Promise.all, i mentre estàs aturat en una les altres nou continuen esperant; amb el timeout normal de 5000 ms, Mocha avortaria la prova sencera als cinc segons, tancant l'aplicació sota els teus peus.

Exercici 3. Reproduir: cridar GET /api/esdeveniments/evt-002/informe amb un organitzador d'org-boveda a la base de proves sembrada; si no es reprodueix, copiar les dades reals d'evt-002, perquè aleshores la fallada és a les dades i no al codi. Aïllar: provar amb evt-001 i evt-003; si només falla evt-002 —el de les tres sessions—, calcular l'informe sessió a sessió per trobar quina produeix NaN. Hipòtesis falsables: que una sessió tingui preuCentims nul i el reduce propagui NaN (perquè undefined * 2 és NaN i el NaN contamina tota la suma), o que l'informe sumi preuEuros en lloc de preuCentims. Bisecció: com que «des d'ahir» acota la finestra, git bisect start, bad HEAD, good <commit d'abans-d'ahir> i git bisect run npm run test:unitat.

Aquesta prova falla en vermell abans de l'arranjament, que té dues parts i totes dues importen: tractar el preu absent com a zero al càlcul (s.preuCentims ?? 0) i fer que el model exigeixi preuCentims, perquè la dada invàlida no hi pugui tornar a entrar. Arreglar només el símptoma deixaria la porta oberta.

Amb aquesta lliçó es tanca el mòdul 9, i amb ell es tanca una escletxa que feia des del mòdul 5 que estava oberta.

Escena Viva ja no descansa sobre la confiança. npm test està verd i significa alguna cosa: el domini calcula bé l'aforament i els totals en cèntims, la matriu de permisos està recorreguda cel·la per cel·la —aquell if invertit a potGestionarEsdeveniment que obriria el catàleg sencer ara posa diverses proves en vermell—, el conversor de divises degrada amb elegància quan el proveïdor cau, l'API respon 401, 403, 404, 409, 422 i 400 amb el format d'error acordat, un assistent no pot veure la comanda d'un altre, i deu compres simultànies per cinc butaques venen exactament cinc butaques. La cobertura està mesurada amb llindars que només pugen, els scripts estan organitzats, i el projecte es pot executar sol en un servidor d'integració contínua. I quan alguna cosa falli —perquè alguna cosa fallarà—, saps reproduir-la, aïllar-la, posar-hi un punt d'interrupció condicional, llegir-ne la traça entre el soroll de node_modules, trobar el commit culpable amb git bisect i convertir-la en una prova que n'impedeixi el retorn.

Aquesta és la xarxa de seguretat. A partir d'ara pots canviar el codi sense por, que era exactament la promesa amb què vam obrir la primera lliçó.

I tanmateix, l'aplicació té un problema del qual les proves no diuen ni una paraula, perquè no és un problema de correcció: és correcta, però és lenta i desaprofita la màquina. Escena Viva fa servir un sol nucli mentre el servidor en té vuit, i a l'estrena del Festival de Jazz de Primavera tots els processos es barallaran per aquell únic fil. Recalcula el mateix catàleg centenars de vegades per minut per retornar sempre el mateix. I quan genera el PDF d'una entrada, bloqueja el bucle d'esdeveniments el temps suficient perquè les altres peticions es quedin esperant a la cua.

Al mòdul 10, Temes Avançats, ataquem justament això: cluster per fer servir tots els nuclis, worker threads per treure la generació de PDF del fil principal, Redis per posar el catàleg a la memòria cau i encuar la feina pesada, optimització del rendiment amb perfils de CPU, flamegraphs i proves de càrrega —la frontera que hem respectat en aquest mòdul—, i per últim el disseny d'APIs RESTful madures i una introducció a GraphQL.