Skip to content

Commit 83f6b3f

Browse files
author
Oswaldo Montaño
committed
docs: add project README
1 parent 4067c84 commit 83f6b3f

1 file changed

Lines changed: 264 additions & 0 deletions

File tree

‎README.md‎

Lines changed: 264 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,264 @@
1+
# GTOOL - Component Testing Orchestrator
2+
3+
<div align="center">
4+
5+
[![Go Version](https://img.shields.io/badge/go-1.24+-00ADD8?logo=go)](https://go.dev/)
6+
![Tests](https://img.shields.io/badge/tests-185%20passing-success)
7+
![Pipeline](https://img.shields.io/badge/pipeline-functional-success)
8+
[![License](https://img.shields.io/badge/license-TBD-blue)](LICENSE)
9+
10+
**CLI en Go para orquestar pruebas de componente de microservicios: levanta mocks, lanza la app, corre los tests y limpia todo — con un solo comando.**
11+
12+
</div>
13+
14+
---
15+
16+
## 🎯 Qué hace GTOOL
17+
18+
```mermaid
19+
graph LR
20+
A[🔧 Mocks] --> B[🚀 App]
21+
B --> C[🧪 Tests Karate]
22+
C --> D[📊 Reporte HTML]
23+
D --> E[🧹 Limpieza]
24+
25+
style A fill:#4fc3f7
26+
style B fill:#66bb6a
27+
style C fill:#ffa726
28+
style D fill:#ab47bc
29+
style E fill:#ef5350
30+
```
31+
32+
GTOOL reemplaza las herramientas bash internas `go-tool` (tests unitarios/build) y `component` (tests de componente) por un único binario en Go, tipado y con logs estructurados. Automatiza:
33+
34+
1. **Mocks** — levanta servicios de terceros en Docker (PostgreSQL, Pub/Sub, Mountebank, Kafka, Couchbase, GCS).
35+
2. **App** — lanza el microservicio bajo prueba (imagen Docker o binarios nativos).
36+
3. **Tests** — ejecuta el suite Karate (backend) contra la app y los mocks.
37+
4. **Reporte** — genera el reporte HTML de Karate y puede abrirlo en el navegador.
38+
5. **Limpieza** — derriba app y mocks siempre, incluso ante fallos o Ctrl-C.
39+
40+
---
41+
42+
## 🚀 Instalación
43+
44+
```bash
45+
git clone <repo-url> && cd gtool
46+
47+
make build # compila ./bin/gtool
48+
./bin/gtool version # verifica
49+
50+
make install # copia el binario a $GOPATH/bin
51+
```
52+
53+
> ⚠️ **`make install` copia a `$GOPATH/bin` (`~/go/bin`).** Si tu terminal no encuentra `gtool` tras instalar, ese directorio no está en tu `PATH`. Agrégalo:
54+
> ```bash
55+
> echo 'export PATH="$PATH:$GOPATH/bin"' >> ~/.zshrc # o ~/.bashrc
56+
> source ~/.zshrc && rehash
57+
> ```
58+
59+
**Requisitos:** Go 1.24+, Docker, Make.
60+
61+
---
62+
63+
## ⚡ Quick Start
64+
65+
```bash
66+
# 1. Validar la configuración del repo
67+
gtool config validate --config component-config.yml
68+
69+
# 2. Levantar solo los mocks
70+
gtool services up
71+
gtool services status
72+
gtool services down
73+
74+
# 3. Pipeline completo (mocks → app → tests → limpieza)
75+
gtool test
76+
```
77+
78+
GTOOL busca por defecto `./component-config.yml`. Usa `--config <archivo>` para otro.
79+
80+
---
81+
82+
## 📖 Comandos
83+
84+
Todos los comandos aceptan `--config <archivo>`, `--log-level debug|info|warn|error` y `--verbose`.
85+
86+
### `gtool config` — configuración
87+
```bash
88+
gtool config validate --config component-config.yml # valida el esquema
89+
gtool config show --format yaml # imprime la config resuelta
90+
gtool config show --format json
91+
```
92+
93+
### `gtool services` (alias `s`) — mocks de terceros
94+
```bash
95+
gtool services up # levanta todos los mocks de la config
96+
gtool s up postgresql kafka # levanta servicios específicos
97+
gtool s status # estado de los servicios
98+
gtool s logs postgresql # logs de un servicio
99+
gtool s down # detiene todos
100+
```
101+
102+
### `gtool app` — aplicación bajo prueba
103+
```bash
104+
gtool app start --docker-image myapp:latest --port 8080
105+
gtool app status
106+
gtool app logs --tail 100
107+
gtool app stop
108+
```
109+
110+
### `gtool unit` (alias `u`) — tests unitarios
111+
Reproduce `go-tool u`: genera los mocks de `build-config.yml` (mockgen) y corre el suite con Ginkgo, dejando cobertura y reporte JUnit en `./coverage`.
112+
```bash
113+
gtool unit
114+
gtool unit --skip-mocks # solo corre los tests
115+
gtool unit --build-config build-config.yml
116+
```
117+
118+
### `gtool test` — pipeline de componente
119+
```bash
120+
gtool test # pipeline nativo de gtool (imágenes públicas)
121+
gtool test karate # solo Karate (mocks y app ya levantados)
122+
gtool test karate --tags "@smoke" --no-open
123+
```
124+
125+
### `gtool generate` / `gtool version`
126+
```bash
127+
gtool generate config # genera un component-config.yml de ejemplo
128+
gtool version
129+
```
130+
131+
---
132+
133+
## 🔁 Reproducir el flujo DIA (`go-tool` / `component`)
134+
135+
Para repos que hoy usan las herramientas bash internas, GTOOL reproduce su comportamiento usando las **imágenes STABLE** privadas y el contrato exacto (red, puertos, montajes, env). Estas rutas son **opt-in** (`--stable`, `--native`) y no alteran el comportamiento nativo de gtool ni el `component-config.yml`.
136+
137+
| Herramienta DIA | Equivalente en GTOOL |
138+
|-----------------|----------------------|
139+
| `go-tool u` | `gtool unit` |
140+
| `component m` (mocks) | `gtool services up --stable` |
141+
| `component r` / `p` (app) | `gtool app start --native` / `gtool app stop --native` |
142+
| `component e` (solo tests) | `gtool test karate` |
143+
| `component t` (pipeline) | `gtool test --stable` |
144+
145+
### Pipeline completo en un comando
146+
```bash
147+
gtool test --stable
148+
```
149+
Esto, en orden: levanta los mocks STABLE → lanza los binarios nativos de la app → corre Karate → **derriba app y mocks siempre** (incluso si los tests fallan o haces Ctrl-C). Flags: `--tags`, `--build-config`, `--no-open`.
150+
151+
### Paso a paso (equivalente, útil para depurar)
152+
```bash
153+
gtool services up --stable # = component m
154+
gtool app start --native # = component r (necesita los binarios en $GOPATH/bin)
155+
gtool test karate # = component e (abre el reporte HTML al terminar)
156+
gtool app stop --native # = component p
157+
gtool services down --stable # detiene los mocks STABLE
158+
```
159+
160+
**Detalles del contrato reproducido:**
161+
- **Mocks STABLE** — `postgresql` (`-p 5432`, monta `test/component/mocks-data/postgresql` → `/data`), `pubsub` (`-p 9085`, env `PROJECT_ID` + `TOPICS` derivados de la config), `mountebank` (`--net=host`, monta `mocks-data/mountebank` → `/imposters`); nombres de contenedor fijos, `--init` y *skip-pull* si la imagen ya está local.
162+
- **App nativa** — lanza `<repo>-<binario>` desde `$GOPATH/bin` (binarios de `build-config.yml`) en puertos `8080+`, con `CUSTOM_SERVER_ADDRESS=0.0.0.0:7080+` y `PUBSUB_EMULATOR_HOST` / `STORAGE_EMULATOR_HOST`.
163+
- **Karate** — corre `test-launcher-back:STABLE` en `--net=host`, monta `test/component/features` → `/app/features` y escribe el reporte en `test/component/reports`; al terminar abre `karate-summary.html` (desactiva con `--no-open`).
164+
165+
> Los binarios de la app deben estar compilados en `$GOPATH/bin` antes de `--native` (p. ej. `go build -o $GOPATH/bin/<repo>-<bin> ./cmd/...`).
166+
167+
---
168+
169+
## 🧩 Configuración
170+
171+
GTOOL usa dos archivos (extensión `.yml` preferida; `.yaml` soportado):
172+
173+
### `component-config.yml` — pipeline de componente
174+
```yaml
175+
version: v1
176+
app-technology: golang # golang | nodejs | generic
177+
test-launcher: test-launcher-back
178+
third-party:
179+
mocks: [postgresql, pubsub, mountebank]
180+
mock-config:
181+
pubsub:
182+
project-id: my-project
183+
topics:
184+
- topic-id: my-topic
185+
subscription-ids: [my-sub]
186+
```
187+
188+
### `build-config.yml` — binarios y mocks de Go (para `gtool unit` / `--native`)
189+
```yaml
190+
version: v5
191+
build:
192+
binaries:
193+
- name: api
194+
path: cmd/server/main.go
195+
mocks:
196+
- source: internal/service/foo_interface.go
197+
filename: foo_interface.go
198+
```
199+
200+
---
201+
202+
## 🏗️ Arquitectura
203+
204+
```mermaid
205+
graph TB
206+
User[👤 Usuario] --> CLI[CLI - Cobra]
207+
CLI --> Orch[Orchestrator]
208+
Orch --> Mock[Mock Manager]
209+
Orch --> App[App Launcher]
210+
Orch --> Test[Test Runner]
211+
Mock --> Plugins[Service Plugins]
212+
Plugins --> Docker[Docker Client]
213+
App --> Docker
214+
Test --> Docker
215+
216+
style CLI fill:#b3e5fc
217+
style Orch fill:#81d4fa
218+
style Mock fill:#4fc3f7
219+
style App fill:#4fc3f7
220+
style Test fill:#4fc3f7
221+
```
222+
223+
- **Plugins** (`internal/plugin/`): `ServicePlugin` (mocks), `AppLauncher`, `TestExecutor`, registrados en un `PluginRegistry` thread-safe.
224+
- **Compat DIA**: `internal/core/mock/stablemocks` (`--stable`), `internal/core/app/nativeapp` (`--native`), `internal/core/test/stablekarate` (`gtool test karate`).
225+
- **Errores tipados** (`pkg/errors`) y **logging estructurado** con Zap (`pkg/logger`).
226+
227+
---
228+
229+
## 🛠️ Desarrollo
230+
231+
```bash
232+
make build # compila ./bin/gtool
233+
make test # tests con -race
234+
make test-coverage # reporte HTML de cobertura
235+
make lint # golangci-lint
236+
make fmt # gofmt + goimports
237+
make clean # limpia artefactos
238+
make help # lista todos los targets
239+
```
240+
241+
**Estándares:** mínimo 80% de cobertura para código nuevo (95%+ en config/orquestación), tests table-driven, errores de `pkg/errors`, conventional commits. Ver [CLAUDE.md](CLAUDE.md).
242+
243+
Tests de integración (requieren Docker) por plugin:
244+
```bash
245+
go test -tags=integration ./internal/plugin/services/...
246+
```
247+
248+
---
249+
250+
## 📦 Estado
251+
252+
Pipeline funcional end-to-end: 6 plugins de mock, lanzador de app (Docker y nativo), runner Karate y orquestación con teardown garantizado. Compatibilidad con el flujo DIA (`go-tool`/`component`) vía rutas opt-in. 185 tests en verde.
253+
254+
| Fase | Estado |
255+
|------|--------|
256+
| 1. Fundamentos (CLI, config, plugins, errores, logging) | ✅ |
257+
| 2. Mocks (6 plugins) | ✅ |
258+
| 3. App Launcher (Docker + nativo) | ✅ |
259+
| 4. Test Executor (Karate) | ✅ |
260+
| 5. Orquestación (pipeline + teardown) | ✅ |
261+
| 6–7. Features avanzadas, docs/release | 🔄 |
262+
263+
---
264+

0 commit comments

Comments
 (0)