Skip to content

The only tool you need to know what is happening and how to fix it.

created devtesting for nestjs

ddux49891b661a0f
diff --git a/testing/devtesting-nestjs/README.md b/testing/devtesting-nestjs/README.md
new file mode 100644
index 00000000..1665ddd7
--- /dev/null
+++ b/testing/devtesting-nestjs/README.md
@@ -0,0 +1,119 @@
+# devtesting-nestjs
+
+NestJS test application for the Traceway JS SDK (`@tracewayapp/nestjs`). Mirrors the Go `devtesting` reference app to validate that all SDK features work correctly in a NestJS environment.
+
+## Running
+
+```bash
+npm install
+npm run start:dev
+```
+
+The app starts on port **3001** by default (configurable via `PORT` env var).
+
+### Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `PORT` | `3001` | Server port |
+| `TRACEWAY_ENDPOINT` | `default_token_change_me@http://localhost:8082/api/report` | Traceway connection string |
+
+## SDK Integration
+
+All `@tracewayapp/nestjs` integration points are used correctly:
+
+| Component | Location | Usage |
+|-----------|----------|-------|
+| `TracewayModule.forRoot()` | `app.module.ts:14` | Configured with `connectionString`, `debug`, `onErrorRecording` |
+| `TracewayMiddleware` | `app.module.ts:34` | Applied globally via `forRoutes("*")` |
+| `TracewayExceptionFilter` | `app.module.ts:27` | Registered as global `APP_FILTER` |
+| `TracewayService` | `app.controller.ts:21`, `app.service.ts:16` | Injected via constructor |
+| `@Span()` decorator | `users.service.ts`, `app.service.ts` | Applied to 8 methods total |
+
+### TracewayService Methods Used
+
+| Method | Location | Purpose |
+|--------|----------|---------|
+| `captureMessage` | `app.service.ts:24` | Log informational messages |
+| `captureException` | `app.service.ts:26` | Report errors |
+| `captureExceptionWithAttributes` | `app.service.ts:71` | Report errors with custom attributes |
+| `startSpan` / `endSpan` | `app.service.ts:45,51` | Manual span creation |
+| `measureTask` | `app.service.ts:57` | Wrap background work as a tracked task |
+| `setTraceAttribute` | `app.service.ts:79` | Attach context attributes to the current trace |
+
+## Endpoints
+
+### App Controller (14 endpoints)
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/test-ok` | Returns `{ status: "ok" }` |
+| GET | `/test-not-found` | Throws 404 HttpException |
+| GET | `/test-exception` | Throws unhandled Error after random delay |
+| GET | `/test-message` | Captures 10 messages + 1 exception via TracewayService |
+| GET | `/test-spans` | Runs nested spans (db.query, cache.set, http.external_api) |
+| GET | `/test-task` | Starts a background task via `measureTask` |
+| GET | `/test-param/:param` | Returns the route param |
+| GET | `/test-self-report-attributes` | Calls `captureExceptionWithAttributes` with custom attrs |
+| GET | `/test-self-report-context` | Sets a trace attribute then captures an exception |
+| GET | `/test-cerror-simple` | Throws a simple Error |
+| GET | `/test-cerror-stacktrace` | Throws an Error from a nested function call |
+| GET | `/test-cerror-wrapped` | Throws a 2-layer wrapped Error (using `cause`) |
+| GET | `/test-cerror-custom` | Throws a CustomError with code + message |
+| POST | `/test-recording/:param` | Accepts JSON body `{ name }`, throws if name != "good" |
+
+### Users Controller (5 endpoints)
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/users` | List all users |
+| GET | `/users/:id` | Get user by ID |
+| POST | `/users` | Create user (`{ firstName, lastName, email }`) |
+| PUT | `/users/:id` | Update user |
+| DELETE | `/users/:id` | Delete user |
+
+All user service methods are decorated with `@Span()` (e.g. `db.users.findAll`, `db.users.create`) and use an in-memory array as the data store with simulated DB delay.
+
+## Comparison with Go devtesting
+
+### Shared Endpoints (15)
+
+Both apps implement: `test-ok`, `test-not-found`, `test-exception`, `test-message`, `test-spans`, `test-task`, `test-param/:param`, `test-self-report-attributes`, `test-self-report-context`, `test-cerror-simple`, `test-cerror-stacktrace`, `test-cerror-wrapped`, `test-cerror-custom`, `test-recording/:param`, and `/users` CRUD.
+
+### Go-Only Endpoints (7)
+
+| Endpoint | Reason Not Ported |
+|----------|-------------------|
+| `/test-json` | Could be ported (not yet implemented) |
+| `/test-50k` | Could be ported (not yet implemented) |
+| `/test-self-report-attributes-panic` | Go-specific — uses `panic()` recovery |
+| `/test-cerror-stacktrace-wrapped` | Go-specific — uses `NewStackTraceErrorf` API |
+| `/test-cerror-multiple` | Go-specific — uses Gin `ctx.Error()` multi-error pattern |
+| `/test-cerror-nested` | Could be ported (not yet implemented) |
+| `/metrics` | Go-specific — uses `PrintCollectionFrameMetrics` API |
+
+### Key Differences
+
+| Aspect | Go devtesting | NestJS devtesting |
+|--------|---------------|-------------------|
+| DB layer | SQLite in-memory with `tracewaydb` wrapper | In-memory array with `@Span()` decorators |
+| DB tracing | Automatic via `tracewaydb` | Manual via `@Span()` on service methods |
+| Panic handling | `traceway.Recover()` + panic endpoints | NestJS exception filters (no panic concept) |
+| Error wrapping | `traceway.NewStackTraceErrorf` | Native JS `Error.cause` chaining |
+| Middleware | `traceway_gin.Use(router, ...)` | `TracewayMiddleware` applied via `NestModule.configure()` |
+| Exception filter | Gin recovery middleware | `TracewayExceptionFilter` as global `APP_FILTER` |
+
+## Project Structure
+
+```
+src/
+├── main.ts # Bootstrap, listens on PORT
+├── app.module.ts # Root module — TracewayModule, middleware, exception filter
+├── app.controller.ts # 14 test endpoints
+├── app.service.ts # TracewayService usage (spans, tasks, errors)
+└── users/
+ ├── users.module.ts # Users feature module
+ ├── users.controller.ts # CRUD endpoints
+ ├── users.service.ts # In-memory store with @Span() decorators
+ └── user.entity.ts # User, CreateUserDto, UpdateUserDto interfaces
+```
diff --git a/testing/devtesting-nestjs/package-lock.json b/testing/devtesting-nestjs/package-lock.json
index 9c0dc2f3..9f8ecf9f 100644
--- a/testing/devtesting-nestjs/package-lock.json
+++ b/testing/devtesting-nestjs/package-lock.json
@@ -24,9 +24,9 @@
},
"../../../js-client/packages/nestjs": {
"name": "@tracewayapp/nestjs",
- "version": "0.1.0",
+ "version": "0.3.0",
"dependencies": {
- "@tracewayapp/backend": "*"
+ "@tracewayapp/backend": "0.3.0"
},
"devDependencies": {
"@types/express": "^4.17.17"