Laboratorio — Entorno de trabajo

Todo el trabajo práctico del curso (laboratorios, Kallpa y el proyecto) se hace con las mismas herramientas para todos: un contenedor Docker con Node.js 26, TypeScript y las herramientas de calidad del curso, más Git y una cuenta de GitHub. Así evitamos el “en mi computadora sí funciona”: si make check pasa en el contenedor, pasa en la revisión y en el pipeline.

1. Requisitos

Además, una cuenta de GitHub y un editor (VS Code o el que prefieran). La imagen es nativa: en una laptop ARM (Apple Silicon) corre como ARM y en una Intel o AMD como x86-64, sin emulación.

2. Levantar el contenedor

Desde la carpeta del repositorio del curso, o la de su proyecto:

./env/run.sh                 # la primera vez construye la imagen (unos minutos)

run.sh monta el directorio actual en /work: los archivos se editan con el editor de siempre en su computadora y se ejecutan en el contenedor. El puerto 3000 del contenedor queda publicado en http://localhost:3000, para ver en el navegador la aplicación que están desarrollando. También acepta un comando:

./env/run.sh make check          # revisa el proyecto: tipos, linter y pruebas
./env/run.sh make test           # corre las pruebas
./env/run.sh --rebuild           # reconstruye la imagen (si cambió el Dockerfile)

Si el contenedor ya está abierto en otra terminal, run.sh abre una segunda shell en el mismo (por ejemplo, una con el servidor corriendo y otra con las pruebas).

3. Qué trae el contenedor

Los paquetes de npm del curso están instalados en la imagen: un import fc from 'fast-check' funciona en cualquier carpeta sin npm install.

4. Git dentro y fuera del contenedor

Git funciona igual en su computadora y en el contenedor. run.sh monta su ~/.gitconfig (solo lectura), así que los commits hechos dentro del contenedor llevan su nombre y su correo. Configúrenlo una vez, en su computadora:

git config --global user.name "Nombre Apellido"
git config --global user.email "su-correo@uni.pe"
git config --global init.defaultBranch main

Para subir y traer cambios de GitHub (git push, git pull), usen la terminal de su computadora, donde ya tienen sus credenciales (SSH o gh auth login). El contenedor no guarda credenciales entre sesiones.

5. Kallpa

kallpa/ es la aplicación de reservas del complejo deportivo Kallpa, escrita para el curso. Casi todos los laboratorios trabajan sobre ella. Su README explica las reglas de negocio y la estructura.

cd kallpa
make check      # tsc, eslint y pruebas
make start      # servidor en http://localhost:3000

Para los laboratorios y para P0 trabajen en su propio repositorio, creado a partir de Kallpa (semana 1), no en la carpeta del curso. En ese repositorio, main se queda igual a la Kallpa publicada en el curso: cada laboratorio empieza en una rama nueva desde main y no se fusiona, así el laboratorio de una semana no depende de cómo quedó el de otra. Si el curso publica una versión nueva de Kallpa, se actualiza main con esa versión.

6. Pruebas con node --test

El runner de Node corre los archivos de prueba que se le indican. Cada archivo usa node:test y node:assert/strict:

import { test } from 'node:test';
import assert from 'node:assert/strict';

test('suma', () => assert.equal(1 + 1, 2));

• node --test "test/**/*.test.ts" corre todas las pruebas (es lo que hace make test en Kallpa); node --test test/pricing.test.ts, un archivo. Sin argumentos, node --test también corre cualquier archivo dentro de una carpeta test/, incluidos los que no son pruebas (como test/helpers.ts): por eso conviene pasarle el patrón.
• node --test --test-name-pattern="cancel" corre las pruebas cuyo nombre contiene cancel.
• node --test --experimental-test-coverage agrega un reporte de cobertura (semana 9).

7. Editar el código

Cualquier editor sirve. Con VS Code, abran la carpeta del repositorio en su computadora: el editor usa su propio TypeScript para marcar errores mientras escriben, y el contenedor corre lo mismo que la revisión. Si instalan Node.js 26 en su computadora, también pueden correr las pruebas fuera del contenedor, pero la referencia es siempre el contenedor.

8. Alternativa: Node.js local

Si no pueden instalar Docker, instalen Node.js 26 y, en la carpeta de su repositorio, las herramientas del curso con las mismas versiones que usa la imagen (ver env/Dockerfile):

npm install --save-dev typescript@6.0.3 @types/node@26.6.6 eslint@10.14.0 \
  @eslint/js@10.0.1 typescript-eslint@8.72.1 fast-check@4.10.2 \
  @stryker-mutator/core@10.1.1 @stryker-mutator/tap-runner@10.1.1 @redocly/cli@2.72.1

y usen npx tsc, npx eslint, etc. Antes de entregar, comprueben en una computadora del laboratorio que make check pasa en el contenedor.

9. Solución de problemas