request-iframe 0.1.0 → 0.2.0

package/README.md

@@ -1,6 +1,6 @@
 # request-iframe
 
-Communicate with iframes like sending HTTP requests! A cross-origin iframe communication library based on `postMessage`.
+Communicate with iframes/windows like sending HTTP requests! A cross-origin browser communication library based on `postMessage`.
 
 > 🌐 **Languages**: [English](./README.md) | [中文](./README.CN.md)
 
@@ -8,7 +8,7 @@ Communicate with iframes like sending HTTP requests! A cross-origin iframe commu
   <img src="https://img.shields.io/badge/TypeScript-Ready-blue" alt="TypeScript Ready">
   <img src="https://img.shields.io/badge/API-Express%20Like-green" alt="Express Like API">
   <img src="https://img.shields.io/badge/License-MIT-yellow" alt="MIT License">
-  <img src="https://img.shields.io/badge/Test%20Coverage-76%25-brightgreen" alt="Test Coverage">
+  <img src="https://coveralls.io/repos/github/gxlmyacc/request-iframe/badge.svg?branch=main" alt="Coverage Status">
 </p>
 
 ## 📑 Table of Contents
@@ -48,7 +48,7 @@ Communicate with iframes like sending HTTP requests! A cross-origin iframe commu
 
 ## Why request-iframe?
 
-In micro-frontend and iframe nesting scenarios, parent-child page communication is a common requirement. Traditional `postMessage` communication has the following pain points:
+In micro-frontend, iframe nesting, and popup window scenarios, cross-page communication is a common requirement. Traditional `postMessage` communication has the following pain points:
 
 | Pain Point | Traditional Way | request-iframe |
 |------------|----------------|----------------|
@@ -74,8 +74,9 @@ In micro-frontend and iframe nesting scenarios, parent-child page communication
 - ⏱️ **Smart Timeout** - Three-stage timeout (connection/sync/async), automatically detects long tasks
 - 📦 **TypeScript** - Complete type definitions and IntelliSense
 - 🔒 **Message Isolation** - secretKey mechanism prevents message cross-talk between multiple instances
-- 📁 **File Transfer** - Support for file sending via stream (client→server)
+- 📁 **File Transfer** - File transfer via streams (client↔server)
 - 🌊 **Streaming** - Support for large file chunked transfer, supports async iterators
+- 🧾 **Leveled Logging** - Warn/Error logs enabled by default; can be configured via `trace` level
 - 🌍 **Internationalization** - Error messages can be customized for i18n
 - ✅ **Protocol Versioning** - Built-in version control for upgrade compatibility
 
@@ -93,6 +94,30 @@ pnpm add request-iframe
 
 **TypeScript**: Built-in complete type definitions, no need to install `@types/request-iframe`
 
+## CDN (UMD bundles)
+
+This repo also builds **script-tag friendly UMD bundles** (core + react hooks) that can be hosted on a CDN.
+
+- Core bundle output: `cdn/request-iframe.umd(.min).js` → global `RequestIframe`
+- React bundle output: `cdn/request-iframe-react.umd(.min).js` → global `RequestIframeReact` (requires `React` global and `RequestIframe` global)
+
+Example (using unpkg):
+
+```html
+<!-- Core -->
+<script src="https://unpkg.com/request-iframe@latest/cdn/request-iframe.umd.min.js"></script>
+
+<!-- React (optional) -->
+<script src="https://unpkg.com/react@latest/umd/react.production.min.js"></script>
+<script src="https://unpkg.com/request-iframe@latest/cdn/request-iframe-react.umd.min.js"></script>
+
+<script>
+  const { requestIframeClient, requestIframeServer, requestIframeEndpoint } = RequestIframe;
+  // React hooks are available on RequestIframeReact (e.g. RequestIframeReact.useClient)
+  console.log(!!requestIframeClient, !!requestIframeServer, !!requestIframeEndpoint);
+<\/script>
+```
+
 ## Quick Start
 
 ### 1. Parent Page (Client Side)
@@ -130,6 +155,11 @@ That's it! 🎉
 
 > 💡 **Tip**: For more quick start guides, see [QUICKSTART.md](./QUICKSTART.md) or [QUICKSTART.CN.md](./QUICKSTART.CN.md) (中文)
 
+## Which API should I use?
+
+- **Use `requestIframeClient()` + `requestIframeServer()`** when communication is mostly one-way (parent → iframe), and you prefer a clear separation between request sender and handler.
+- **Use `requestIframeEndpoint()`** when you need **bidirectional** communication (both sides need `send()` + `on()/use()/map()`), or when you want a single façade object to debug a full flow more easily.
+
 ---
 
 ## Use Cases
@@ -172,6 +202,29 @@ server.on('/event', (req, res) => {
 });
 ```
 
+### Popup / New Window (Window Communication)
+
+`request-iframe` also works with a `Window` target (not only an iframe).
+
+**Important**: you must have a real `Window` reference (e.g. returned by `window.open()`, or available via `window.opener` / `event.source`). You cannot send to an arbitrary browser tab by URL.
+
+```typescript
+// Parent page: open a new tab/window
+const child = window.open('https://child.example.com/page.html', '_blank');
+if (!child) throw new Error('Popup blocked');
+
+// Parent -> child
+const client = requestIframeClient(child, {
+  secretKey: 'popup-demo',
+  targetOrigin: 'https://child.example.com' // strongly recommended (avoid '*')
+});
+await client.send('/api/ping', { from: 'parent' });
+
+// Child page: create server
+const server = requestIframeServer({ secretKey: 'popup-demo' });
+server.on('/api/ping', (req, res) => res.send({ ok: true, echo: req.body }));
+```
+
 ### Cross-Origin Data Fetching
 
 When iframe and parent page are on different origins, use request-iframe to securely fetch data:
@@ -237,7 +290,7 @@ request-iframe implements an HTTP-like communication protocol on top of `postMes
        │                                          │
        │  <──── RESPONSE ──────────────────────  │  Return result
        │                                          │
-       │  ──── RECEIVED (optional) ────────────>  │  Acknowledge receipt of response/error (controlled by response `requireAck`)
+       │  ──── ACK (optional) ─────────────────>  │  Acknowledge receipt of response/error (ACK-only requireAck)
        │                                          │
 ```
 
@@ -246,15 +299,13 @@ request-iframe implements an HTTP-like communication protocol on top of `postMes
 | Type | Direction | Description |
 |------|-----------|-------------|
 | `request` | Client → Server | Client initiates request |
-| `ack` | Server → Client | Server acknowledges receipt of request (when request `requireAck` is enabled) |
+| `ack` | Receiver → Sender | Acknowledgment when `requireAck: true` and the message is accepted/handled (ACK-only) |
 | `async` | Server → Client | Notifies client this is an async task (sent when handler returns Promise) |
 | `response` | Server → Client | Returns response data |
 | `error` | Server → Client | Returns error information |
-| `received` | Client → Server | Client acknowledges receipt of response/error (optional, controlled by response `requireAck`) |
 | `ping` | Client → Server | Connection detection (`isConnect()` method, may use `requireAck` to confirm delivery) |
 | `pong` | Server → Client | Connection detection response |
 | `stream_pull` | Receiver → Sender | Stream pull: receiver requests next chunks (pull/ack protocol) |
-| `stream_ack` | Receiver → Sender | Stream ack: receiver acknowledges a chunk (pull/ack protocol) |
 
 ### Timeout Mechanism
 
@@ -558,6 +609,8 @@ server.on('/api/data', (req, res) => {
 
 ### File Transfer
 
+> Note: File transfer (both Client→Server and Server→Client) is carried by the stream protocol under the hood. You normally only need to use `client.sendFile()` / `res.sendFile()`.
+
 #### Server → Client (Server sends file to client)
 
 ```typescript
@@ -592,7 +645,7 @@ if (response.data instanceof File || response.data instanceof Blob) {
 
 #### Client → Server (Client sends file to server)
 
-Client sends file via stream only. Use `sendFile()` (or `send(path, file)`); server receives either `req.body` as File/Blob when `autoResolve: true` (default), or `req.stream` as `IframeFileReadableStream` when `autoResolve: false`.
+Client sends file using `sendFile()` (or `send(path, file)`); server receives either `req.body` as File/Blob when `autoResolve: true` (default), or `req.stream` as `IframeFileReadableStream` when `autoResolve: false`.
 
 ```typescript
 // Client side: Send file (stream, autoResolve defaults to true)
@@ -616,16 +669,71 @@ server.on('/api/upload', async (req, res) => {
 });
 ```
 
-**Note:** When using `client.send()` with a `File` or `Blob`, it automatically dispatches to `client.sendFile()`, which sends the file via stream. Server gets `req.body` as File/Blob when `autoResolve` is true (default), or `req.stream` / `req.body` as `IframeFileReadableStream` when `autoResolve` is false.
+**Note:** When using `client.send()` with a `File` or `Blob`, it automatically dispatches to `client.sendFile()`. Server gets `req.body` as File/Blob when `autoResolve` is true (default), or `req.stream` / `req.body` as `IframeFileReadableStream` when `autoResolve` is false.
 
 ### Streaming
 
-For large files or scenarios requiring chunked transfer, you can use streaming:
+Streaming is not only for large/chunked transfers, but also works well for **long-lived subscription-style interactions** (similar to SSE/WebSocket, but built on top of `postMessage`).
+
+#### Long-lived subscription (push mode)
+
+> Notes:
+> - `IframeWritableStream` defaults `expireTimeout` to `asyncTimeout` to avoid leaking long-lived streams. For real subscriptions, set a larger `expireTimeout`, or set `expireTimeout: 0` to disable auto-expire (use with care and pair with cancel/reconnect).
+> - `res.sendStream(stream)` waits until the stream ends. If you want to keep pushing via `write()`, **do not** `await` it; use `void res.sendStream(stream)` or keep the returned Promise.
+> - If `maxConcurrentRequestsPerClient` is enabled, a long-lived stream occupies one in-flight request slot.
+> - **Event subscription**: streams support `stream.on(event, listener)` (returns an unsubscribe function) for observability (e.g. `start/data/read/write/cancel/end/error/timeout/expired`). For consuming data, prefer `for await`.
+
+```typescript
+/**
+ * Server side: subscribe (long-lived)
+ * - mode: 'push': writer calls write()
+ * - expireTimeout: 0: disable auto-expire (use with care)
+ */
+server.on('/api/subscribe', (req, res) => {
+  const stream = new IframeWritableStream({
+    type: 'data',
+    chunked: true,
+    mode: 'push',
+    expireTimeout: 0,
+    /** optional: writer-side idle timeout while waiting for pull/ack */
+    streamTimeout: 15000
+  });
+
+  /** do not await, otherwise it blocks until stream ends */
+  void res.sendStream(stream);
+
+  const timer = setInterval(() => {
+    try {
+      stream.write({ type: 'tick', ts: Date.now() });
+    } catch {
+      clearInterval(timer);
+    }
+  }, 1000);
+});
+
+/**
+ * Client side: consume continuously (prefer for-await for long-lived streams)
+ */
+const resp = await client.send('/api/subscribe', {});
+if (isIframeReadableStream(resp.stream)) {
+  /** Optional: observe events */
+  const off = resp.stream.on(StreamEvent.ERROR, ({ error }) => {
+    console.error('stream error:', error);
+  });
+
+  for await (const evt of resp.stream) {
+    console.log('event:', evt);
+  }
+
+  off();
+}
+```
 
 #### Server → Client (Server sends stream to client)
 
 ```typescript
-import { 
+import {
+  StreamEvent,
   IframeWritableStream, 
   IframeFileWritableStream,
   isIframeReadableStream,
@@ -740,21 +848,23 @@ server.on('/api/uploadStream', async (req, res) => {
 
 | Type | Description |
 |------|-------------|
-| `IframeWritableStream` | Server-side writable stream for sending regular data |
-| `IframeFileWritableStream` | Server-side file writable stream, automatically handles base64 encoding |
-| `IframeReadableStream` | Client-side readable stream for receiving regular data |
-| `IframeFileReadableStream` | Client-side file readable stream, automatically handles base64 decoding |
+| `IframeWritableStream` | Writer/producer stream: **created by whichever side is sending the stream** (server→client response stream, or client→server request stream) |
+| `IframeFileWritableStream` | File writer/producer stream (base64-encodes internally) |
+| `IframeReadableStream` | Reader/consumer stream for receiving regular data (regardless of which side sent it) |
+| `IframeFileReadableStream` | File reader/consumer stream (base64-decodes internally) |
 
 > **Note**: File streams are base64-encoded internally. Base64 introduces ~33% size overhead and can be memory/CPU heavy for very large files. For large files, prefer **chunked** file streams (`chunked: true`) and keep chunk sizes moderate (e.g. 256KB–1MB).
 
 **Stream timeouts:**
-- `options.streamTimeout` (request option): client-side stream idle timeout while consuming `response.stream` (data/file streams). When triggered, the client will attempt a heartbeat check and fail the stream if the connection is not alive.
+- `options.streamTimeout` (request option): client-side stream idle timeout while consuming `response.stream` (data/file streams). When triggered, the client performs a heartbeat check (by default `client.isConnect()`); if not alive, the stream fails as disconnected.
 - `expireTimeout` (writable stream option): writer-side stream lifetime. When expired, the writer sends `stream_error` and the reader will fail the stream with `STREAM_EXPIRED`.
-- `streamTimeout` (writable stream option): writer-side idle timeout. If the writer does not receive `stream_pull/stream_ack` for a long time, it will heartbeat-check and fail to avoid wasting resources.
+- `streamTimeout` (writable stream option): writer-side idle timeout. If the writer does not receive `stream_pull` for a long time, it will heartbeat-check and fail to avoid wasting resources.
+- `maxPendingChunks` (writable stream option): max number of pending (unsent) chunks kept in memory on the writer side (optional). Important for long-lived `push` streams: if the receiver stops pulling, continued `write()` calls will accumulate in the writer queue.
+- `maxPendingBytes` (writable stream option): max bytes of pending (unsent) chunks kept in memory on the writer side (optional). Useful when a single `write()` may enqueue a very large chunk.
 
 **Pull/Ack protocol (default):**
-- Reader automatically sends `stream_pull` to request chunks and sends `stream_ack` for each received chunk.
 - Writer only sends `stream_data` when it has received `stream_pull`, enabling real backpressure.
+  - Disconnect detection does not rely on a dedicated per-frame ack message type, but uses `streamTimeout + heartbeat(isConnect)`.
 
 **consume default change:**
 - `for await (const chunk of response.stream)` defaults to **consume and drop** already iterated chunks (`consume: true`) to prevent unbounded memory growth for long streams.
@@ -778,9 +888,9 @@ Server can require Client to acknowledge receipt of response:
 ```typescript
 server.on('/api/important', async (req, res) => {
   // requireAck: true means client needs to acknowledge
-  const received = await res.send(data, { requireAck: true });
+  const acked = await res.send(data, { requireAck: true });
   
-  if (received) {
+  if (acked) {
     console.log('Client acknowledged receipt');
   } else {
     console.log('Client did not acknowledge (timeout)');
@@ -788,21 +898,25 @@ server.on('/api/important', async (req, res) => {
 });
 ```
 
-> **Note**: Client acknowledgment (`received`) is sent automatically by the library when the response/error is accepted by the client (i.e., there is a matching pending request). You don't need to manually send `received`.
+> **Note**: Client acknowledgment (`ack`) is sent automatically by the library when the response/error is accepted by the client (i.e., there is a matching pending request). You don't need to manually send `ack`.
 
 ### Trace Mode
 
-Enable trace mode to view detailed communication logs in console:
+By default, request-iframe only prints **warn/error** logs (to avoid noisy console in production).
+
+Enable trace mode (or set a log level) to view detailed communication logs:
 
 ```typescript
+import { LogLevel } from 'request-iframe';
+
 const client = requestIframeClient(iframe, { 
   secretKey: 'demo',
-  trace: true 
+  trace: true // equivalent to LogLevel.TRACE
 });
 
 const server = requestIframeServer({ 
   secretKey: 'demo',
-  trace: true 
+  trace: LogLevel.INFO // enable info/warn/error logs (less verbose than trace)
 });
 
 // Console output:
@@ -811,6 +925,14 @@ const server = requestIframeServer({
 // [request-iframe] [INFO] ✅ Request Success { status: 200, data: {...} }
 ```
 
+`trace` supports:
+- `true` / `false`
+- `'trace' | 'info' | 'warn' | 'error' | 'silent'` (or `LogLevel.*`)
+
+Notes:
+- When `trace` is `LogLevel.TRACE` or `LogLevel.INFO`, the library will also attach built-in debug interceptors/listeners for richer request/response logs.
+- When `trace` is `LogLevel.WARN` / `LogLevel.ERROR` / `LogLevel.SILENT`, it only affects log output level (no extra debug interceptors attached).
+
 ### Internationalization
 
 ```typescript
@@ -841,7 +963,7 @@ Create a Client instance.
 |-----------|------|-------------|
 | `target` | `HTMLIFrameElement \| Window` | Target iframe element or window object |
 | `options.secretKey` | `string` | Message isolation identifier (optional) |
-| `options.trace` | `boolean` | Whether to enable trace mode (optional) |
+| `options.trace` | `boolean \| 'trace' \| 'info' \| 'warn' \| 'error' \| 'silent'` | Trace/log level (optional). Default logs are warn/error only |
 | `options.targetOrigin` | `string` | Override postMessage targetOrigin for sending (optional). If `target` is a `Window`, default is `*`. |
 | `options.ackTimeout` | `number` | Global default ACK acknowledgment timeout (ms), default 1000 |
 | `options.timeout` | `number` | Global default request timeout (ms), default 5000 |
@@ -853,6 +975,70 @@ Create a Client instance.
 
 **Returns:** `RequestIframeClient`
 
+**Notes about `target: Window`:**
+- **You must have a `Window` reference** (e.g. from `window.open()`, `window.opener`, or `MessageEvent.source`).
+- You **cannot** communicate with an arbitrary browser tab by URL.
+- For security, prefer setting a strict `targetOrigin` and configure `allowedOrigins` / `validateOrigin`.
+
+**Production configuration template:**
+
+```typescript
+import { requestIframeClient, requestIframeServer } from 'request-iframe';
+
+/**
+ * Recommended: explicitly constrain 3 things
+ * - secretKey: isolate different apps/instances (avoid cross-talk)
+ * - targetOrigin: postMessage targetOrigin (strongly avoid '*' for Window targets)
+ * - allowedOrigins / validateOrigin: incoming origin allowlist validation
+ */
+const secretKey = 'my-app';
+const targetOrigin = 'https://child.example.com';
+const allowedOrigins = [targetOrigin];
+
+// Client (parent)
+const client = requestIframeClient(window.open(targetOrigin)!, {
+  secretKey,
+  targetOrigin,
+  allowedOrigins
+});
+
+// Server (child/iframe)
+const server = requestIframeServer({
+  secretKey,
+  allowedOrigins,
+  // Mitigate message explosion (tune as needed)
+  maxConcurrentRequestsPerClient: 50
+});
+```
+
+**Production configuration template (iframe target):**
+
+```typescript
+import { requestIframeClient, requestIframeServer } from 'request-iframe';
+
+/**
+ * For iframe targets, you can derive targetOrigin from iframe.src, and use it as the allowedOrigins allowlist.
+ */
+const iframe = document.querySelector('iframe')!;
+const targetOrigin = new URL(iframe.src).origin;
+const secretKey = 'my-app';
+
+// Client (parent)
+const client = requestIframeClient(iframe, {
+  secretKey,
+  // Explicitly set it (even though the library can derive it) to avoid accidentally using '*'
+  targetOrigin,
+  allowedOrigins: [targetOrigin]
+});
+
+// Server (inside iframe)
+const server = requestIframeServer({
+  secretKey,
+  allowedOrigins: [targetOrigin],
+  maxConcurrentRequestsPerClient: 50
+});
+```
+
 ### requestIframeServer(options?)
 
 Create a Server instance.
@@ -862,7 +1048,7 @@ Create a Server instance.
 | Parameter | Type | Description |
 |-----------|------|-------------|
 | `options.secretKey` | `string` | Message isolation identifier (optional) |
-| `options.trace` | `boolean` | Whether to enable trace mode (optional) |
+| `options.trace` | `boolean \| 'trace' \| 'info' \| 'warn' \| 'error' \| 'silent'` | Trace/log level (optional). Default logs are warn/error only |
 | `options.ackTimeout` | `number` | Wait for client acknowledgment timeout (ms), default 1000 |
 | `options.maxConcurrentRequestsPerClient` | `number` | Max concurrent in-flight requests per client (per origin + creatorId). Default Infinity |
 | `options.allowedOrigins` | `string \| RegExp \| Array<string \| RegExp>` | Allowlist for incoming message origins (optional, recommended for production) |
@@ -870,6 +1056,65 @@ Create a Server instance.
 
 **Returns:** `RequestIframeServer`
 
+### requestIframeEndpoint(target, options?)
+
+Create an **endpoint facade** (client + server) for a peer window/iframe.
+
+It can:
+- **send requests** to the peer: `endpoint.send(...)`
+- **handle requests** from the peer: `endpoint.on(...)`, `endpoint.use(...)`, `endpoint.map(...)`
+
+Notes:
+- Client and server instances are **lazily created** (only when you first access send/handlers APIs).
+- `options.id` (if provided) becomes the shared ID for both sides (client + server); otherwise a random one is generated.
+- `options.trace` follows the same leveled logging rules as client/server (`LogLevel.*` recommended).
+
+Example (bidirectional via endpoint, recommended):
+
+```typescript
+import { requestIframeEndpoint, LogLevel } from 'request-iframe';
+
+// Parent page (has iframe element)
+const iframe = document.querySelector('iframe')!;
+const parentEndpoint = requestIframeEndpoint(iframe, {
+  secretKey: 'demo',
+  trace: LogLevel.INFO
+});
+parentEndpoint.on('/notify', (req, res) => res.send({ ok: true, echo: req.body }));
+
+// Iframe page (has window.parent)
+const iframeEndpoint = requestIframeEndpoint(window.parent, {
+  secretKey: 'demo',
+  targetOrigin: 'https://parent.example.com',
+  trace: true
+});
+iframeEndpoint.on('/api/ping', (req, res) => res.send({ ok: true }));
+
+// Either side can now send + handle
+await parentEndpoint.send('/api/ping', { from: 'parent' });
+await iframeEndpoint.send('/notify', { from: 'iframe' });
+```
+
+Production configuration template (recommended):
+
+```typescript
+import { requestIframeEndpoint, LogLevel } from 'request-iframe';
+
+const secretKey = 'my-app';
+const iframe = document.querySelector('iframe')!;
+const targetOrigin = new URL(iframe.src).origin;
+
+const endpoint = requestIframeEndpoint(iframe, {
+  secretKey,
+  targetOrigin,
+  allowedOrigins: [targetOrigin],
+  // Mitigate message explosion (tune as needed)
+  maxConcurrentRequestsPerClient: 50,
+  // Logs: default is warn/error; choose info for debugging
+  trace: LogLevel.WARN
+});
+```
+
 ### Client API
 
 #### client.send(path, body?, options?)
@@ -1447,7 +1692,11 @@ Just ensure both sides use the same `secretKey`.
 
 ### 4. Can Server actively push messages?
 
-request-iframe is request-response mode, Server cannot actively push. For bidirectional communication, you can create a Client inside the iframe:
+request-iframe is request-response mode, Server cannot actively push by itself.
+
+For bidirectional communication, you have 2 options:
+- Create a reverse `client` inside the iframe (traditional way)
+- Use `requestIframeEndpoint()` on both sides (recommended) so each side has **send + handle** in one object
 
 ```typescript
 // Inside iframe
@@ -1460,10 +1709,11 @@ await client.send('/notify', { event: 'data-changed' });
 
 ### 5. How to debug communication issues?
 
-1. **Enable trace mode**: View detailed communication logs
+1. **Enable logs with levels**: by default only warn/error logs are printed; enable `trace: LogLevel.INFO` (or `trace: true`) to see detailed logs
 2. **Check secretKey**: Ensure Client and Server use the same secretKey
 3. **Check iframe loading**: Ensure iframe is fully loaded
-4. **Check console**: Check for cross-origin errors
+4. **Check origin constraints**: prefer setting strict `targetOrigin` and configure `allowedOrigins` / `validateOrigin`
+5. **Consider using `requestIframeEndpoint()`**: it unifies both directions (send + handle) and makes it easier to debug flows in one place
 
 ---
 
@@ -1515,12 +1765,7 @@ yarn build
 
 ### Test Coverage
 
-The project currently has **76.88%** test coverage, meeting production requirements:
-
-- **Statement Coverage**: 76.88%
-- **Branch Coverage**: 64.13%
-- **Function Coverage**: 75%
-- **Line Coverage**: 78.71%
+The project maintains **high test coverage** and CI coverage reports (see badges at the top of this README).
 
 Coverage reports are generated in the `coverage/` directory, view detailed coverage report via `coverage/index.html`.