@rlabs-cl/arketum 0.0.0-stage → 1.0.0

package/catalogo-de-ejemplo/stacks/go/suelo-aplicacion-por-capas/terminal_prueba.py

@@ -0,0 +1,118 @@
+"""
+TERMINAL DE PRUEBA (fijación del catálogo de Arketum: se copia tal cual y no se
+edita). Prueba un programa de terminal como lo usaría una persona, en una
+pseudo-terminal emulada con pyte (`python3 -m pip install pyte`).
+
+    from terminal_prueba import Terminal
+
+    with Terminal(['sh', 'arrancar.sh'], cwd='.', columnas=80, filas=24) as t:
+        t.esperar(2)                 # deja correr el programa
+        t.tecla('ARRIBA')            # ARRIBA, ABAJO, IZQUIERDA, DERECHA, ENTER, ESC o un carácter
+        t.esperar(0.5)
+        texto = t.pantalla()         # lo que se ve, una cadena con una línea por fila
+        assert t.vivo()              # sigue corriendo
+        assert 'Traceback' not in texto
+
+`t.lineas()` da la lista de filas y `t.codigo` el código de salida cuando termina.
+"""
+
+import fcntl, os, pty, select, signal, struct, termios, time
+
+import pyte
+
+TECLAS = {'ARRIBA': b'\x1b[A', 'ABAJO': b'\x1b[B', 'DERECHA': b'\x1b[C', 'IZQUIERDA': b'\x1b[D', 'ENTER': b'\r', 'ESC': b'\x1b'}
+
+
+class Terminal:
+    def __init__(self, comando, cwd='.', columnas=80, filas=24, env=None):
+        self._pantalla = pyte.Screen(columnas, filas)
+        self._flujo = pyte.ByteStream(self._pantalla)
+        pid, fd = pty.fork()
+        if pid == 0:
+            entorno = dict(os.environ, LANG='en_US.UTF-8', LC_ALL='en_US.UTF-8', TERM='xterm-256color', COLUMNS=str(columnas), LINES=str(filas))
+            entorno.update(env or {})
+            os.chdir(cwd)
+            os.execvpe(comando[0], comando, entorno)
+        fcntl.ioctl(fd, termios.TIOCSWINSZ, struct.pack('HHHH', filas, columnas, 0, 0))
+        self.pid, self.fd, self._vivo, self.codigo = pid, fd, True, None
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *_):
+        self.cerrar()
+
+    def esperar(self, segundos):
+        fin = time.time() + segundos
+        while time.time() < fin:
+            r, _, _ = select.select([self.fd], [], [], 0.05)
+            if r:
+                try:
+                    datos = os.read(self.fd, 65536)
+                except OSError:
+                    datos = b''
+                if datos:
+                    self._flujo.feed(datos)
+                else:
+                    time.sleep(0.05)
+            self._comprobar()
+        self._comprobar()
+
+    def tecla(self, nombre):
+        datos = TECLAS.get(nombre, nombre.encode() if isinstance(nombre, str) else nombre)
+        # Como un terminal real: si el programa activó el modo de cursor de aplicación (DECCKM, el modo privado 1, que pyte guarda como 1 << 5; curses
+        # con keypad), las flechas van como ESC O x en vez de ESC [ x.
+        if datos[:2] == b'\x1b[' and len(datos) == 3 and datos[2:] in b'ABCD' and (1 << 5) in self._pantalla.mode:
+            datos = b'\x1bO' + datos[2:]
+        try:
+            os.write(self.fd, datos)
+        except OSError:
+            pass
+
+    def pantalla(self):
+        return '\n'.join(self._pantalla.display)
+
+    def lineas(self):
+        return list(self._pantalla.display)
+
+    def pintadas(self):
+        """Cuántas celdas se ven: con carácter, en vídeo inverso o con un fondo distinto del
+        dominante (al borrar, pyte rellena con el fondo del cursor: ese no cuenta)."""
+        from collections import Counter
+        filas, cols = self._pantalla.lines, self._pantalla.columns
+        celdas = [self._pantalla.buffer[y][x] for y in range(filas) for x in range(cols)]
+        fondo = Counter(c.bg for c in celdas).most_common(1)[0][0]
+        return sum(1 for c in celdas if c.data.strip() or c.reverse or c.bg != fondo)
+
+    def foto(self):
+        """Lo que se ve, con forma: el texto y dónde hay celdas en vídeo inverso o con fondo distinto del dominante."""
+        from collections import Counter
+        filas, cols = self._pantalla.lines, self._pantalla.columns
+        fondo = Counter(self._pantalla.buffer[y][x].bg for y in range(filas) for x in range(cols)).most_common(1)[0][0]
+        marcas = tuple((y, x) for y in range(filas) for x in range(cols) if self._pantalla.buffer[y][x].reverse or self._pantalla.buffer[y][x].bg != fondo)
+        return (self.pantalla(), marcas)
+
+    def vivo(self):
+        self._comprobar()
+        return self._vivo
+
+    def _comprobar(self):
+        if not self._vivo:
+            return
+        p, estado = os.waitpid(self.pid, os.WNOHANG)
+        if p != 0:
+            self._vivo = False
+            self.codigo = os.waitstatus_to_exitcode(estado)
+
+    def cerrar(self):
+        if self._vivo:
+            try:
+                os.kill(self.pid, signal.SIGKILL)
+                os.waitpid(self.pid, 0)
+            except OSError:
+                pass
+            self._vivo = False
+        try:
+            os.close(self.fd)
+        except OSError:
+            pass

package/catalogo-de-ejemplo/stacks/go/suelo-juego-terminal/requirements.txt

@@ -0,0 +1 @@
+pyte

package/catalogo-de-ejemplo/stacks/go/suelo-juego-terminal/suelo.py

@@ -0,0 +1,86 @@
+#!/usr/bin/env python3
+"""
+SUELO FIJO de la forma `juego-terminal` (fijación del catálogo de Arketum: se
+copia tal cual en `arketum/fijaciones/suelo/` y no se edita; el cierre compara su
+checksum). Las comprobaciones de uso que no escribe quien construye: que el
+programa vive, no que el juego esté bien.
+
+Arranca el artefacto por su contrato de arranque: `sh arrancar.sh` desde su raíz.
+
+  arranca    a 80x24, a los 3 s sigue vivo, pinta algo y sin traza
+  se_mueve   sin tocar nada, en 2.4 s se ven al menos 5 fotogramas distintos (un juego en tiempo real anima)
+  aguanta    8 s más con flechas pulsadas, vivo y sin traza
+  sale_q     con `q` termina
+  pequena    a 30x10 no saca traza (avisa o sale limpio)
+
+Uso: python3 arketum/fijaciones/suelo/suelo.py <raíz del artefacto>  →  JSON; código 0 si pasa, 1 si no.
+Necesita `pyte` (`python3 -m pip install -r arketum/fijaciones/suelo/requirements.txt`).
+"""
+
+import faulthandler, json, os, sys
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+from terminal_prueba import Terminal  # noqa: E402
+
+ARRANQUE = ['sh', 'arrancar.sh']
+
+
+def pintadas(t):
+    """Lo más pintado en unas cuantas muestras: un juego que borra y redibuja puede pillarse a medias."""
+    n = 0
+    for _ in range(5):
+        t.esperar(0.15)
+        n = max(n, t.pintadas())
+    return n
+
+
+def evaluar(raiz):
+    if not os.path.isfile(os.path.join(raiz, 'arrancar.sh')):
+        return {'ok': False, 'fallo': 'no hay `arrancar.sh` en la raíz del artefacto: es su contrato de arranque', 'pantalla': ''}
+    r = {'comando': ' '.join(ARRANQUE)}
+    with Terminal(ARRANQUE, cwd=raiz, columnas=80, filas=24) as t:
+        t.tecla('ENTER')  # por si hay una pantalla de inicio que espera una tecla
+        t.esperar(3)
+        n = pintadas(t)
+        texto = t.pantalla()
+        r['arranca'] = t.vivo() and 'Traceback' not in texto and n >= 10
+        if not r['arranca']:
+            return {**r, 'ok': False, 'fallo': 'a 80x24 no arranca: muere, saca una traza o no pinta nada', 'pantalla': texto}
+        # Movimiento: muchos fotogramas distintos. Un juego que borra y redibuja parpadea entre dos
+        # estados (completo y vacío), y el parpadeo no es movimiento.
+        fotos = set()
+        for _ in range(12):
+            t.esperar(0.2)
+            fotos.add(t.foto())
+        r['se_mueve'] = len(fotos) >= 5
+        if not r['se_mueve']:
+            return {**r, 'ok': False, 'fallo': 'la pantalla no cambia sola: no hay nada en movimiento', 'pantalla': t.pantalla()}
+        for i in range(32):
+            t.tecla('ARRIBA' if (i // 4) % 2 else 'ABAJO')
+            t.esperar(0.25)
+            if not t.vivo():
+                break
+        texto = t.pantalla()
+        r['aguanta'] = t.vivo() and 'Traceback' not in texto
+        if not r['aguanta']:
+            return {**r, 'ok': False, 'fallo': 'jugando 8 s con flechas, el programa muere o saca una traza', 'pantalla': texto}
+        t.tecla('q')
+        t.esperar(3)
+        r['sale_q'] = not t.vivo()
+        if not r['sale_q']:
+            return {**r, 'ok': False, 'fallo': 'con `q` el programa no termina', 'pantalla': t.pantalla()}
+    with Terminal(ARRANQUE, cwd=raiz, columnas=30, filas=10) as t:
+        t.esperar(2.5)
+        texto = t.pantalla()
+        r['pequena'] = 'Traceback' not in texto and (t.vivo() or t.codigo == 0)
+        if not r['pequena']:
+            return {**r, 'ok': False, 'fallo': 'a 30x10 saca una traza o sale con error en vez de avisar', 'pantalla': texto}
+    return {**r, 'ok': True}
+
+
+if __name__ == '__main__':
+    # Un suelo nunca se queda colgado: a los 150 s escribe dónde estaba y termina con error (1).
+    faulthandler.dump_traceback_later(150, exit=True)
+    resultado = evaluar(os.path.abspath(sys.argv[1] if len(sys.argv) > 1 else '.'))
+    print(json.dumps(resultado, ensure_ascii=False, indent=1))
+    sys.exit(0 if resultado['ok'] else 1)

package/catalogo-de-ejemplo/stacks/go/suelo-juego-terminal/terminal_prueba.py

@@ -0,0 +1,118 @@
+"""
+TERMINAL DE PRUEBA (fijación del catálogo de Arketum: se copia tal cual y no se
+edita). Prueba un programa de terminal como lo usaría una persona, en una
+pseudo-terminal emulada con pyte (`python3 -m pip install pyte`).
+
+    from terminal_prueba import Terminal
+
+    with Terminal(['sh', 'arrancar.sh'], cwd='.', columnas=80, filas=24) as t:
+        t.esperar(2)                 # deja correr el programa
+        t.tecla('ARRIBA')            # ARRIBA, ABAJO, IZQUIERDA, DERECHA, ENTER, ESC o un carácter
+        t.esperar(0.5)
+        texto = t.pantalla()         # lo que se ve, una cadena con una línea por fila
+        assert t.vivo()              # sigue corriendo
+        assert 'Traceback' not in texto
+
+`t.lineas()` da la lista de filas y `t.codigo` el código de salida cuando termina.
+"""
+
+import fcntl, os, pty, select, signal, struct, termios, time
+
+import pyte
+
+TECLAS = {'ARRIBA': b'\x1b[A', 'ABAJO': b'\x1b[B', 'DERECHA': b'\x1b[C', 'IZQUIERDA': b'\x1b[D', 'ENTER': b'\r', 'ESC': b'\x1b'}
+
+
+class Terminal:
+    def __init__(self, comando, cwd='.', columnas=80, filas=24, env=None):
+        self._pantalla = pyte.Screen(columnas, filas)
+        self._flujo = pyte.ByteStream(self._pantalla)
+        pid, fd = pty.fork()
+        if pid == 0:
+            entorno = dict(os.environ, LANG='en_US.UTF-8', LC_ALL='en_US.UTF-8', TERM='xterm-256color', COLUMNS=str(columnas), LINES=str(filas))
+            entorno.update(env or {})
+            os.chdir(cwd)
+            os.execvpe(comando[0], comando, entorno)
+        fcntl.ioctl(fd, termios.TIOCSWINSZ, struct.pack('HHHH', filas, columnas, 0, 0))
+        self.pid, self.fd, self._vivo, self.codigo = pid, fd, True, None
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *_):
+        self.cerrar()
+
+    def esperar(self, segundos):
+        fin = time.time() + segundos
+        while time.time() < fin:
+            r, _, _ = select.select([self.fd], [], [], 0.05)
+            if r:
+                try:
+                    datos = os.read(self.fd, 65536)
+                except OSError:
+                    datos = b''
+                if datos:
+                    self._flujo.feed(datos)
+                else:
+                    time.sleep(0.05)
+            self._comprobar()
+        self._comprobar()
+
+    def tecla(self, nombre):
+        datos = TECLAS.get(nombre, nombre.encode() if isinstance(nombre, str) else nombre)
+        # Como un terminal real: si el programa activó el modo de cursor de aplicación (DECCKM, el modo privado 1, que pyte guarda como 1 << 5; curses
+        # con keypad), las flechas van como ESC O x en vez de ESC [ x.
+        if datos[:2] == b'\x1b[' and len(datos) == 3 and datos[2:] in b'ABCD' and (1 << 5) in self._pantalla.mode:
+            datos = b'\x1bO' + datos[2:]
+        try:
+            os.write(self.fd, datos)
+        except OSError:
+            pass
+
+    def pantalla(self):
+        return '\n'.join(self._pantalla.display)
+
+    def lineas(self):
+        return list(self._pantalla.display)
+
+    def pintadas(self):
+        """Cuántas celdas se ven: con carácter, en vídeo inverso o con un fondo distinto del
+        dominante (al borrar, pyte rellena con el fondo del cursor: ese no cuenta)."""
+        from collections import Counter
+        filas, cols = self._pantalla.lines, self._pantalla.columns
+        celdas = [self._pantalla.buffer[y][x] for y in range(filas) for x in range(cols)]
+        fondo = Counter(c.bg for c in celdas).most_common(1)[0][0]
+        return sum(1 for c in celdas if c.data.strip() or c.reverse or c.bg != fondo)
+
+    def foto(self):
+        """Lo que se ve, con forma: el texto y dónde hay celdas en vídeo inverso o con fondo distinto del dominante."""
+        from collections import Counter
+        filas, cols = self._pantalla.lines, self._pantalla.columns
+        fondo = Counter(self._pantalla.buffer[y][x].bg for y in range(filas) for x in range(cols)).most_common(1)[0][0]
+        marcas = tuple((y, x) for y in range(filas) for x in range(cols) if self._pantalla.buffer[y][x].reverse or self._pantalla.buffer[y][x].bg != fondo)
+        return (self.pantalla(), marcas)
+
+    def vivo(self):
+        self._comprobar()
+        return self._vivo
+
+    def _comprobar(self):
+        if not self._vivo:
+            return
+        p, estado = os.waitpid(self.pid, os.WNOHANG)
+        if p != 0:
+            self._vivo = False
+            self.codigo = os.waitstatus_to_exitcode(estado)
+
+    def cerrar(self):
+        if self._vivo:
+            try:
+                os.kill(self.pid, signal.SIGKILL)
+                os.waitpid(self.pid, 0)
+            except OSError:
+                pass
+            self._vivo = False
+        try:
+            os.close(self.fd)
+        except OSError:
+            pass

package/catalogo-de-ejemplo/stacks/go.yaml

@@ -0,0 +1,74 @@
+# Stack: Go.
+#
+# Toma las ubicaciones de `servicio-con-integracion` (1.1.0): cada paquete en
+# `internal/`, con las pruebas `<nombre>_test.go` junto a lo que prueban; cada
+# ubicación de código las excluye, para que solo las reclame `prueba`.
+#
+# Cambios:
+# - 1.1.0: las fijaciones de `juego-terminal` y de `aplicacion-por-capas` (los suelos y la ayuda e2e por
+#   terminal, de caja negra en Python), sus comandos y `arrancar.sh` como
+#   arranque; las pruebas e2e en `tests/e2e/`; lo que genera Python.
+# - 1.2.0: `noEjecutan`, los argumentos con que el ejecutor de la suite e2e
+#   (pytest) no ejecuta ninguna prueba, que antes sabía Arketum. TRANSICIÓN: la
+#   huella del stack y la del efectivo cambian; los descensos certificados con la
+#   anterior dan `stale_policy` hasta recertificarlos.
+name: go
+version: 1.2.0
+description: >-
+  Go: un módulo por artefacto, con sus paquetes en `internal/` y las pruebas `<nombre>_test.go` junto al código; `go.mod` y `go.sum` como módulo, `cmd/<binario>/main.go` y `arrancar.sh` como arranque, y las pruebas de extremo a extremo, de caja negra, en `tests/e2e/`.
+
+ubicaciones:
+  modulo: { pattern: "go.<fichero>" }
+  dominio: { pattern: "internal/dominio/<nombre>.go", excluding: ["internal/dominio/<nombre>_test.go"] }
+  almacen: { pattern: "internal/almacen/<nombre>.go", excluding: ["internal/almacen/<nombre>_test.go"] }
+  servicio: { pattern: "internal/servicios/<nombre>.go", excluding: ["internal/servicios/<nombre>_test.go"] }
+  interfaz: { pattern: "internal/interfaz/<nombre>.go", excluding: ["internal/interfaz/<nombre>_test.go"] }
+  api: { pattern: "internal/api/<nombre>.go", excluding: ["internal/api/<nombre>_test.go"] }
+  cliente: { pattern: "internal/clientes/<nombre>.go", excluding: ["internal/clientes/<nombre>_test.go"] }
+  arranque: { pattern: ["cmd/<binario>/main.go", "arrancar.sh"] }
+  prueba: { pattern: ["internal/<paquete>/<nombre>_test.go", "tests/e2e/<nombre>.py"] }
+
+muestras:
+  modulo: [go.mod, go.sum]
+  dominio: [internal/dominio/pedido.go]
+  almacen: [internal/almacen/sqlite.go]
+  servicio: [internal/servicios/pedidos.go]
+  interfaz: [internal/interfaz/web.go]
+  api: [internal/api/rutas.go]
+  cliente: [internal/clientes/catalogo.go]
+  arranque: [cmd/tienda/main.go, arrancar.sh]
+  prueba: [internal/servicios/pedidos_test.go, internal/dominio/pedido_test.go, tests/e2e/test_partida.py, tests/e2e/conftest.py]
+
+# Lo que generan las pruebas e2e y las fijaciones, que son de Python.
+generados: [__pycache__/, .pytest_cache/]
+
+oficio:
+  - Toda frontera con otro sistema es una interfaz que el servicio declara tal como la necesita, con un doble para probar sin el sistema real.
+  - 'Los errores se devuelven y se envuelven con contexto (`fmt.Errorf("…: %w", err)`); nunca se ignoran ni se convierten en `panic`.'
+  - Ningún paquete de `internal/` importa `cmd/`; el cableado vive en `cmd/<binario>/main.go`.
+  - El contexto (`context.Context`) viaja como primer parámetro en lo que habla con fuera.
+  - '`arrancar.sh` compila y lanza el binario (`go run ./cmd/<binario> "$@"`, o el binario ya construido): es lo que lanzan el suelo y las pruebas e2e.'
+  - Las pruebas e2e (`tests/e2e/`, de caja negra, con pytest) arrancan el programa con el lanzador `app` (o `juego`) de la fijación e2e y lo usan por la terminal, como una persona. Las fijaciones necesitan `python3` con `pyte` y `pytest` (`python3 -m pip install -r arketum/fijaciones/e2e/requirements.txt`), que son de las pruebas, no del producto.
+
+# Fijas del catálogo: se copian tal cual en `arketum/fijaciones/<nombre>/` del
+# artefacto y no se editan (el cierre compara su checksum).
+fijaciones:
+  - { de: stacks/go/suelo-juego-terminal, nombre: suelo, para: suelo, formas: [juego-terminal] }
+  - { de: stacks/go/suelo-aplicacion-por-capas, nombre: suelo, para: suelo, formas: [aplicacion-por-capas] }
+  - { de: stacks/go/e2e-terminal, nombre: e2e, para: e2e, formas: [juego-terminal, aplicacion-por-capas] }
+
+# Los argumentos con los que su ejecutor de pruebas de la suite e2e (pytest, por la ayuda e2e de caja negra) no ejecuta ninguna: una
+# ejecución de la suite e2e con uno de ellos no cuenta como e2e.
+noEjecutan: [--co, --collect-only, --collectonly, --trace-config, --help, -h, --version, -V, --fixtures, --fixtures-per-test, --markers, --setup-plan, --setup-only]
+
+comandos:
+  pruebas: go test ./...
+  suelo: python3 -B arketum/fijaciones/suelo/suelo.py .
+  e2e: PYTHONPATH=arketum/fijaciones/e2e python3 -B -m pytest -q -c arketum/fijaciones/e2e/pytest.ini --rootdir=. tests/e2e
+
+
+selfReview:
+  criteria:
+    - check: La cobertura de pruebas del código propio es al menos del 80%
+      how: Corre `go test -cover ./...` y lee el total.
+      evidence: medida

package/catalogo-de-ejemplo/stacks/python/e2e-terminal/e2e_http.py

@@ -0,0 +1,36 @@
+"""Peticiones HTTP para las pruebas de extremo a extremo (fijación del catálogo de Arketum: no se edita). Solo la biblioteca estándar."""
+import json, urllib.error, urllib.parse, urllib.request
+
+
+def _hacer(req, timeout=15):
+    try:
+        with urllib.request.urlopen(req, timeout=timeout) as r:
+            return r.status, r.read().decode('utf8', 'replace')
+    except urllib.error.HTTPError as e:
+        return e.code, e.read().decode('utf8', 'replace')
+
+
+def get(url, **params):
+    if params:
+        url += ('&' if '?' in url else '?') + urllib.parse.urlencode(params)
+    return _hacer(url)
+
+
+def get_json(url, **params):
+    st, t = get(url, **params)
+    try:
+        return st, json.loads(t)
+    except ValueError:
+        return st, t
+
+
+def post_json(url, datos, metodo='POST'):
+    st, t = _hacer(urllib.request.Request(url, data=json.dumps(datos).encode(), method=metodo, headers={'Content-Type': 'application/json'}))
+    try:
+        return st, json.loads(t)
+    except ValueError:
+        return st, t
+
+
+def post_form(url, datos):
+    return _hacer(urllib.request.Request(url, data=urllib.parse.urlencode(datos).encode(), headers={'Content-Type': 'application/x-www-form-urlencoded'}))

package/catalogo-de-ejemplo/stacks/python/e2e-terminal/pytest.ini

@@ -0,0 +1,5 @@
+# Fijación del catálogo de Arketum: no se edita. La suite e2e se corre desde la
+# raíz del artefacto con:
+#   PYTHONPATH=arketum/fijaciones/e2e python3 -m pytest -q -c arketum/fijaciones/e2e/pytest.ini --rootdir=. tests/e2e
+[pytest]
+addopts = -p terminal_e2e -p no:cacheprovider --confcutdir=.

package/catalogo-de-ejemplo/stacks/python/e2e-terminal/requirements.txt

@@ -0,0 +1,2 @@
+pyte
+pytest

package/catalogo-de-ejemplo/stacks/python/e2e-terminal/terminal_e2e.py

@@ -0,0 +1,112 @@
+"""
+AYUDA E2E (fijación del catálogo de Arketum: se copia tal cual en
+`arketum/fijaciones/e2e/` y no se edita; el cierre compara su checksum). Es un
+complemento de pytest que carga `pytest.ini` (`-p terminal_e2e`), con la carpeta en `PYTHONPATH`:
+
+    PYTHONPATH=arketum/fijaciones/e2e python3 -m pytest -q -c arketum/fijaciones/e2e/pytest.ini --rootdir=. tests/e2e
+
+Arranca el artefacto por el camino real, con su contrato de arranque
+(`sh arrancar.sh` desde su raíz), con datos nuevos: `HOME` y `DATOS_DIR` en una
+carpeta temporal propia y `PUERTO` libre. Las pruebas de `tests/e2e/` usan:
+
+- `app` (o `juego`): un lanzador.
+  - `app()` (o `app(columnas, filas)`): la aplicación en una terminal emulada
+    (`Terminal` de `terminal_prueba`: `tecla`, `esperar`, `pantalla`, `vivo`…).
+  - `app.reabrir()`: cierra lo abierto y vuelve a arrancar con los mismos datos.
+  - `app.servidor()`: la arranca sin terminal (para una aplicación que sirve
+    HTTP en `PUERTO`) y espera a que responda; devuelve su URL base.
+  - `app.url`, `app.datos`: la URL base (`http://127.0.0.1:<PUERTO>`) y la
+    carpeta de datos.
+- `e2e_http` (módulo): `get`, `get_json`, `post_json`, `post_form`.
+
+Una prueba e2e recorre lo que haría una persona por la interfaz real: nunca
+importa el código del artefacto ni llama a sus funciones por dentro.
+"""
+
+import os, signal, socket, subprocess, sys, tempfile, time, urllib.error, urllib.request
+
+import pytest
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+
+ARRANQUE = ['sh', 'arrancar.sh']
+
+
+def _libre():
+    with socket.socket() as s:
+        s.bind(('127.0.0.1', 0))
+        return s.getsockname()[1]
+
+
+def _responde(url):
+    try:
+        urllib.request.urlopen(url, timeout=2)
+        return True
+    except urllib.error.HTTPError:
+        return True
+    except Exception:  # noqa: BLE001
+        return False
+
+
+class Lanzador:
+    def __init__(self, raiz):
+        self.raiz = raiz
+        self.casa = tempfile.mkdtemp(prefix='e2e-')
+        self.datos = os.path.join(self.casa, 'datos')
+        self.puerto = _libre()
+        self.url = f'http://127.0.0.1:{self.puerto}'
+        self.abiertas = []
+        self.procesos = []
+
+    def entorno(self):
+        return {'HOME': self.casa, 'DATOS_DIR': self.datos, 'PUERTO': str(self.puerto), 'PYTHONUNBUFFERED': '1'}
+
+    def __call__(self, columnas=80, filas=24):
+        from terminal_prueba import Terminal  # necesita pyte; solo si se usa la terminal
+
+        t = Terminal(ARRANQUE, cwd=self.raiz, columnas=columnas, filas=filas, env=self.entorno())
+        self.abiertas.append(t)
+        return t
+
+    def reabrir(self, columnas=80, filas=24):
+        self.cerrar()
+        return self(columnas, filas)
+
+    def servidor(self, ruta='/', segundos=25):
+        p = subprocess.Popen(ARRANQUE, cwd=self.raiz, env=dict(os.environ, **self.entorno()), stdin=subprocess.PIPE, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL, start_new_session=True)
+        self.procesos.append(p)
+        fin = time.time() + segundos
+        while time.time() < fin:
+            if p.poll() is not None:
+                raise AssertionError(f'`sh arrancar.sh` terminó con código {p.returncode} antes de responder en {self.url}')
+            if _responde(self.url + ruta):
+                return self.url
+            time.sleep(0.2)
+        raise AssertionError(f'`sh arrancar.sh` no respondió en {self.url}{ruta} en {segundos} s')
+
+    def cerrar(self):
+        for t in self.abiertas:
+            t.cerrar()
+        self.abiertas = []
+        for p in self.procesos:
+            try:
+                os.killpg(p.pid, signal.SIGTERM)
+                p.wait(timeout=5)
+            except Exception:  # noqa: BLE001
+                try:
+                    os.killpg(p.pid, signal.SIGKILL)
+                except Exception:  # noqa: BLE001
+                    pass
+        self.procesos = []
+
+
+@pytest.fixture
+def app(request):
+    l = Lanzador(str(request.config.rootpath))
+    yield l
+    l.cerrar()
+
+
+@pytest.fixture
+def juego(app):
+    return app