@gcoredev/fastedge-test 0.0.1-beta.4 → 0.1.0-beta.2

package/docs/DEBUGGER.md

@@ -0,0 +1,151 @@
+# Debugger Server
+
+Runs the FastEdge debugger HTTP server, which hosts the web UI, REST API, and WebSocket endpoint for loading and testing WASM modules.
+
+## CLI Usage
+
+The package exposes a `fastedge-debug` binary. Run it with `npx` without installing:
+
+```bash
+npx @gcoredev/fastedge-test
+```
+
+Or using the explicit binary name:
+
+```bash
+npx fastedge-debug
+```
+
+Once started, the server listens on `http://localhost:5179` by default and logs the bound address to stdout.
+
+## Programmatic Usage
+
+Import `startServer` from the `./server` export to start the server from your own script or test setup:
+
+```typescript
+import { startServer } from "@gcoredev/fastedge-test/server";
+
+// Start on the default port (5179)
+await startServer();
+
+// Start on a custom port
+await startServer(3000);
+```
+
+**Signature:**
+
+```typescript
+function startServer(port?: number): Promise<void>;
+```
+
+The returned promise resolves once the server is bound and ready to accept connections.
+
+**Example: start and stop in a test setup**
+
+```typescript
+import { startServer } from "@gcoredev/fastedge-test/server";
+
+// Start server for integration tests
+await startServer(5200);
+
+// ... run tests ...
+
+// Send SIGTERM to trigger graceful shutdown
+process.kill(process.pid, "SIGTERM");
+```
+
+## Port Configuration
+
+| Source         | Value                 |
+| -------------- | --------------------- |
+| Default        | `5179`                |
+| `PORT` env var | Any valid port number |
+
+```bash
+PORT=8080 npx fastedge-debug
+```
+
+When `WORKSPACE_PATH` is set, the server writes the bound port number to `$WORKSPACE_PATH/.debug-port` on startup and deletes it on shutdown.
+
+## Health Check
+
+```
+GET /health
+```
+
+Returns `200 OK` with a JSON body:
+
+```json
+{
+  "status": "ok",
+  "service": "fastedge-debugger"
+}
+```
+
+Use this endpoint to verify the server is running before sending requests. The `service` field is always `"fastedge-debugger"`.
+
+```bash
+curl http://localhost:5179/health
+```
+
+## Environment Variables
+
+| Variable             | Type     | Default | Description                                                                                   |
+| -------------------- | -------- | ------- | --------------------------------------------------------------------------------------------- |
+| `PORT`               | `number` | `5179`  | Port the HTTP server listens on                                                               |
+| `PROXY_RUNNER_DEBUG` | `"1"`    | unset   | Enable verbose debug logging for WebSocket and runner activity                                |
+| `WORKSPACE_PATH`     | `string` | unset   | Absolute path to the workspace root; used as the `.env` file base and for port file placement |
+| `FASTEDGE_RUN_PATH`  | `string` | unset   | Override the path to the `fastedge-run` CLI binary used to execute WASM modules               |
+
+### Usage examples
+
+```bash
+# Enable debug logging
+PROXY_RUNNER_DEBUG=1 npx fastedge-debug
+
+# Use a non-default port with debug logging
+PORT=8080 PROXY_RUNNER_DEBUG=1 npx fastedge-debug
+
+# Point to a workspace and override the fastedge-run binary
+WORKSPACE_PATH=/home/user/myproject \
+FASTEDGE_RUN_PATH=/usr/local/bin/fastedge-run \
+npx fastedge-debug
+```
+
+## Graceful Shutdown
+
+The server handles `SIGTERM` and `SIGINT`:
+
+1. Logs the received signal
+2. Cleans up the active WASM runner (frees memory, closes child processes)
+3. Closes all WebSocket connections
+4. Deletes the `.debug-port` file (if `WORKSPACE_PATH` is set)
+5. Closes the HTTP server
+6. Exits with code `0`
+
+The `.debug-port` file is also deleted on the Node.js `exit` event, which covers Windows environments where `SIGTERM` is not delivered.
+
+Send `SIGTERM` to trigger shutdown programmatically:
+
+```bash
+kill -SIGTERM <pid>
+```
+
+Or press `Ctrl+C` in the terminal to send `SIGINT`.
+
+## Web UI
+
+When the server starts, it serves a browser-based UI at the root URL:
+
+```
+http://localhost:5179
+```
+
+The UI provides a graphical interface for loading WASM modules, configuring requests, and inspecting results. All UI interactions use the same REST and WebSocket endpoints available to API consumers.
+
+## See Also
+
+- [API.md](API.md) — REST endpoint reference for loading WASM, sending requests, and managing configuration
+- [WEBSOCKET.md](WEBSOCKET.md) — WebSocket protocol, event types, and real-time state updates
+- [TEST_FRAMEWORK.md](TEST_FRAMEWORK.md) — Programmatic test framework for writing automated WASM tests
+- [TEST_CONFIG.md](TEST_CONFIG.md) — `fastedge-config.test.json` schema and configuration options

package/docs/INDEX.md

@@ -0,0 +1,111 @@
+# fastedge-test Documentation
+
+`@gcoredev/fastedge-test` — local test runner and debugger for FastEdge WASM modules.
+
+## Documentation Files
+
+| File                                    | Audience              | Description                                                                                      |
+| --------------------------------------- | --------------------- | ------------------------------------------------------------------------------------------------ |
+| [quickstart.md](quickstart.md)          | All users             | Install, configure, and run your first test in under five minutes                                |
+| [TEST_FRAMEWORK.md](TEST_FRAMEWORK.md)  | Test authors          | High-level API (`defineTestSuite`, `runTestSuite`, assertions) for writing automated test suites |
+| [TEST_CONFIG.md](TEST_CONFIG.md)        | Test authors          | `fastedge-config.test.json` schema — all fields, defaults, and validation rules                  |
+| [RUNNER.md](RUNNER.md)                  | Advanced / CI tooling | Low-level programmatic API for direct runner lifecycle control                                   |
+| [DEBUGGER.md](DEBUGGER.md)              | All users             | `fastedge-debug` CLI — starting the interactive debugger server                                  |
+| [API.md](API.md)                        | Tooling integrators   | HTTP REST API exposed by the debugger server                                                     |
+| [WEBSOCKET.md](WEBSOCKET.md)            | Tooling integrators   | WebSocket event stream API for real-time server events                                           |
+
+## Quick Links
+
+| Goal                                             | Start here                             |
+| ------------------------------------------------ | -------------------------------------- |
+| Writing tests for a WASM module                  | [TEST_FRAMEWORK.md](TEST_FRAMEWORK.md) |
+| Understanding the test config file format        | [TEST_CONFIG.md](TEST_CONFIG.md)       |
+| Running the interactive debugger UI              | [DEBUGGER.md](DEBUGGER.md)             |
+| Building custom CI or automation tooling         | [API.md](API.md)                       |
+| Subscribing to real-time server events           | [WEBSOCKET.md](WEBSOCKET.md)           |
+| Direct runner control without the test framework | [RUNNER.md](RUNNER.md)                 |
+| First time using this package                    | [quickstart.md](quickstart.md)         |
+
+## Package Exports
+
+| Entry point | Description                                                                                    |
+| ----------- | ---------------------------------------------------------------------------------------------- |
+| `.`         | Main entry — runner API and core types                                                         |
+| `./test`    | Test framework API — use this for writing and running test suites                              |
+| `./server`  | Debugger server entry — used by the `fastedge-debug` CLI binary; not intended for direct import |
+| `./schemas` | JSON Schema files for `fastedge-config.test.json` — reference in editors for validation        |
+
+### `@gcoredev/fastedge-test` (`.`)
+
+Exports the low-level runner API. See [RUNNER.md](RUNNER.md) for full reference.
+
+```typescript
+import { createRunner, createRunnerFromBuffer } from "@gcoredev/fastedge-test";
+```
+
+| Export                 | Kind     | Description                                               |
+| ---------------------- | -------- | --------------------------------------------------------- |
+| `createRunner`         | function | Creates a runner instance from a WASM file path           |
+| `createRunnerFromBuffer` | function | Creates a runner instance from a `Buffer` or `Uint8Array` |
+| `ProxyWasmRunner`      | class    | Runner implementation for proxy-wasm (CDN) modules        |
+| `HttpWasmRunner`       | class    | Runner implementation for HTTP WASM modules               |
+| `WasmRunnerFactory`    | class    | Factory for creating the appropriate runner by WASM type  |
+| `NullStateManager`     | class    | No-op state manager for stateless runner use              |
+| `IWasmRunner`          | type     | Interface all runner implementations satisfy              |
+| `IStateManager`        | type     | Interface for runner state managers                       |
+| `WasmType`             | type     | Union of supported WASM module types                      |
+| `RunnerConfig`         | type     | Configuration options passed to runner constructors       |
+| `HttpRequest`          | type     | HTTP request shape used by the runner                     |
+| `HttpResponse`         | type     | HTTP response shape returned by the runner                |
+| `HookResult`           | type     | Result of a single proxy-wasm hook invocation             |
+| `FullFlowResult`       | type     | Aggregated result of a complete request flow              |
+| `HookCall`             | type     | Descriptor for a proxy-wasm hook call                     |
+
+### `@gcoredev/fastedge-test/test`
+
+Exports the high-level test framework. See [TEST_FRAMEWORK.md](TEST_FRAMEWORK.md) for full reference.
+
+```typescript
+import { defineTestSuite, runAndExit } from "@gcoredev/fastedge-test/test";
+```
+
+| Export                    | Kind     | Description                                                          |
+| ------------------------- | -------- | -------------------------------------------------------------------- |
+| `defineTestSuite`         | function | Validates and returns a typed `TestSuite` definition                 |
+| `runTestSuite`            | function | Executes a `TestSuite` and returns a `SuiteResult`                   |
+| `runAndExit`              | function | Runs a suite and exits the process with a pass/fail code             |
+| `runFlow`                 | function | Executes a single request flow directly                              |
+| `loadConfigFile`          | function | Loads and validates a `fastedge-config.test.json` file               |
+| `assertRequestHeader`     | function | Asserts a header is present on the outgoing request                  |
+| `assertNoRequestHeader`   | function | Asserts a header is absent from the outgoing request                 |
+| `assertResponseHeader`    | function | Asserts a header is present on the final response                    |
+| `assertNoResponseHeader`  | function | Asserts a header is absent from the final response                   |
+| `assertFinalStatus`       | function | Asserts the final HTTP status code                                   |
+| `assertFinalHeader`       | function | Asserts a header on the final response (alias for response header)   |
+| `assertReturnCode`        | function | Asserts the proxy-wasm return code                                   |
+| `assertLog`               | function | Asserts a log entry was emitted                                      |
+| `assertNoLog`             | function | Asserts a log entry was not emitted                                  |
+| `logsContain`             | function | Returns whether logs contain a matching entry                        |
+| `hasPropertyAccessViolation` | function | Returns whether any property access violation was recorded        |
+| `assertPropertyAllowed`   | function | Asserts that a WASM property read was allowed                        |
+| `assertPropertyDenied`    | function | Asserts that a WASM property read was denied                         |
+| `TestSuite`               | type     | Suite definition — one of `wasmPath` or `wasmBuffer` plus test cases |
+| `TestCase`                | type     | A single test scenario with config and assertions                    |
+| `TestResult`              | type     | Result of a single test case execution                               |
+| `SuiteResult`             | type     | Aggregated result returned by `runTestSuite`                         |
+| `FlowOptions`             | type     | Options accepted by `runFlow`                                        |
+| `RunnerConfig`            | type     | Configuration options for the underlying runner                      |
+
+### `@gcoredev/fastedge-test/server`
+
+The debugger server entrypoint. This export is used internally by the `fastedge-debug` binary and is not intended for direct import. Start the server via the CLI instead — see [DEBUGGER.md](DEBUGGER.md).
+
+### `@gcoredev/fastedge-test/schemas`
+
+Directory of JSON Schema files. Point your editor's `$schema` field at the appropriate file to enable validation and autocompletion in `fastedge-config.test.json`. See [TEST_CONFIG.md](TEST_CONFIG.md) for usage.
+
+## Internal Documentation
+
+Contributors and developers working in this repository should refer to the internal context documentation:
+
+- [`context/CONTEXT_INDEX.md`](../context/CONTEXT_INDEX.md) — discovery-based index of all internal developer docs