refactor: Enhance examples and add documentation tests

Consolidates the React examples into a single `App.jsx` to improve clarity and maintenance, deprecating `HooksExampleApp.js`.
Adds SEO metadata to Next.js App Router pages.
Introduces dedicated tests for documented core and browser client functionalities, ensuring consistency and validating usage patterns.
Makes `EventBuilder.markAsCritical` parameter optional, defaulting to `true` for improved usability.
Includes minor corrections in the root `README.md` and internalizes a `next-request.js` helper function.

Author: niemyjski

README.md

@@ -150,9 +150,9 @@ import { Exceptionless } from "@exceptionless/browser";
 await Exceptionless.submitLog("Logging made easy");
 
 // You can also specify the log source and log level.
-// We recommend specifying one of the following log levels: Trace, Debug, Info, Warn, Error
-await Exceptionless.submitLog("app.logger", "This is so easy", "Info");
-await Exceptionless.createLog("app.logger", "This is so easy", "Info").addTags("Exceptionless").submit();
+// We recommend specifying one of the following log levels: trace, debug, info, warn, error
+await Exceptionless.submitLog("app.logger", "This is so easy", "info");
+await Exceptionless.createLog("app.logger", "This is so easy", "info").addTags("Exceptionless").submit();
 
 // Submit feature usages
 await Exceptionless.submitFeatureUsage("MyFeature");
@@ -163,7 +163,7 @@ await Exceptionless.submitNotFound("/somepage");
 await Exceptionless.createNotFound("/somepage").addTags("Exceptionless").submit();
 
 // Submit a custom event type
-await Exceptionless.submitEvent({ message = "Low Fuel", type = "racecar", source = "Fuel System" });
+await Exceptionless.submitEvent({ message: "Low Fuel", type: "racecar", source: "Fuel System" });
 ```
 
 #### Manually submitting Errors

example/nextjs/app/page.jsx

@@ -1,5 +1,10 @@
 import ClientDemoPanel from "../components/ClientDemoPanel.jsx";
 
+export const metadata = {
+  title: "Exceptionless Next.js Example",
+  description: "Client and server Exceptionless integration demo for the Next.js App Router."
+};
+
 export default function HomePage() {
   const deploymentTarget = process.env.VERCEL_ENV ?? "local";
 

example/nextjs/app/server-component-error/page.jsx

@@ -1,4 +1,8 @@
 export const dynamic = "force-dynamic";
+export const metadata = {
+  title: "Server Component Error Demo",
+  description: "Demonstration route for Exceptionless App Router server component failures."
+};
 
 export default function ServerComponentErrorPage() {
   throw new Error("Server component crash from the Exceptionless Next.js demo");

example/nextjs/lib/next-request.js

@@ -15,7 +15,7 @@ export function buildRequestContextFromOnRequestError(request) {
   });
 }
 
-export function buildRequestContext({ method, pathOrUrl, headers, body }) {
+function buildRequestContext({ method, pathOrUrl, headers, body }) {
   const normalizedHeaders = normalizeHeaders(headers);
   const origin = getOrigin(normalizedHeaders);
   const url = new URL(pathOrUrl, origin);

example/react/README.md

@@ -1,6 +1,6 @@
 ## Exceptionless React Example
 
-This example shows how to use the `@exceptionless/react` package. There is both a class component example (App.js) and a function component example with hooks (HooksExampleApp.js).
+This example shows how to use the `@exceptionless/react` package with an error boundary around a component that can throw during render.
 
 The package includes [error boundary support](https://reactjs.org/docs/error-boundaries.html) which means uncaught errors inside your components will automatically be sent to Exceptionless.
 

example/react/src/App.jsx

@@ -2,6 +2,41 @@ import React, { Component } from "react";
 import "./App.css";
 import { Exceptionless, ExceptionlessErrorBoundary } from "@exceptionless/react";
 
+function ExceptionlessExampleContent({ error, message, errorInfo, onThrowComponentError, onUnhandledException, onSubmitMessage, onTryCatchExample }) {
+  if (error) {
+    throw new Error("I crashed!");
+  }
+
+  return (
+    <div className="App">
+      <header className="App-header">
+        <div className="container">
+          <h1 className="App-title">Exceptionless React Sample</h1>
+          <p>By pressing the button below, an uncaught error will be thrown inside your component. This will automatically be sent to Exceptionless.</p>
+          <button onClick={onThrowComponentError}>Simulate Error</button>
+          <div>
+            <p>Throw an uncaught error and make sure Exceptionless tracks it.</p>
+            <button onClick={onUnhandledException}>Throw unhandled error</button>
+          </div>
+          <p>The following buttons simulated handled events outside the component.</p>
+          <button onClick={onSubmitMessage}>Submit Message</button>
+          {message && (
+            <p>
+              Message sent to Exceptionless: <code>{message}</code>
+            </p>
+          )}
+          <button onClick={onTryCatchExample}>Try/Catch Example</button>
+          {errorInfo && (
+            <p>
+              Error message sent to Exceptionless: <code>{errorInfo}</code>
+            </p>
+          )}
+        </div>
+      </header>
+    </div>
+  );
+}
+
 class App extends Component {
   constructor(props) {
     super(props);
@@ -46,43 +81,24 @@ class App extends Component {
     throw new Error("Unhandled exception");
   };
 
-  renderExample = () => {
-    if (this.state.error) {
-      throw new Error("I crashed!");
-    } else {
-      return (
-        <div className="App">
-          <header className="App-header">
-            <div className="container">
-              <h1 className="App-title">Exceptionless React Sample</h1>
-              <p>By pressing the button below, an uncaught error will be thrown inside your component. This will automatically be sent to Exceptionless.</p>
-              <button onClick={this.throwErrorInComponent}>Simulate Error</button>
-              <div>
-                <p>Throw an uncaught error and make sure Exceptionless tracks it.</p>
-                <button onClick={this.unhandledExceptionExample}>Throw unhandled error</button>
-              </div>
-              <p>The following buttons simulated handled events outside the component.</p>
-              <button onClick={this.submitMessage}>Submit Message</button>
-              {this.state.message && (
-                <p>
-                  Message sent to Exceptionless: <code>{this.state.message}</code>
-                </p>
-              )}
-              <button onClick={this.tryCatchExample}>Try/Catch Example</button>
-              {this.state.errorInfo && (
-                <p>
-                  Error message sent to Exceptionless: <code>{this.state.errorInfo}</code>
-                </p>
-              )}
-            </div>
-          </header>
-        </div>
-      );
-    }
-  };
-
   render() {
-    return <ExceptionlessErrorBoundary>{this.renderExample()}</ExceptionlessErrorBoundary>;
+    return (
+      <ExceptionlessErrorBoundary>
+        <ExceptionlessExampleContent
+          error={this.state.error}
+          message={this.state.message}
+          errorInfo={this.state.errorInfo}
+          onThrowComponentError={this.throwErrorInComponent}
+          onUnhandledException={this.unhandledExceptionExample}
+          onSubmitMessage={() => {
+            void this.submitMessage();
+          }}
+          onTryCatchExample={() => {
+            void this.tryCatchExample();
+          }}
+        />
+      </ExceptionlessErrorBoundary>
+    );
   }
 }
 

example/react/src/HooksExampleApp.js

@@ -0,0 +1,28 @@
+import { describe, expect, test } from "vitest";
+
+import { BrowserExceptionlessClient } from "../src/BrowserExceptionlessClient.js";
+
+describe("BrowserExceptionlessClient", () => {
+  test("should configure documented browser plugins on first startup", async () => {
+    const client = new BrowserExceptionlessClient();
+
+    await client.startup((config) => {
+      config.apiKey = "UNIT_TEST_API_KEY";
+      config.updateSettingsWhenIdleInterval = -1;
+    });
+
+    try {
+      const pluginNames = client.config.plugins.map((plugin) => plugin.name);
+
+      expect(pluginNames).toContain("BrowserGlobalHandlerPlugin");
+      expect(pluginNames).toContain("BrowserIgnoreExtensionErrorsPlugin");
+      expect(pluginNames).toContain("BrowserLifeCyclePlugin");
+      expect(pluginNames).toContain("BrowserModuleInfoPlugin");
+      expect(pluginNames).toContain("BrowserRequestInfoPlugin");
+      expect(pluginNames).toContain("BrowserErrorPlugin");
+      expect(pluginNames).not.toContain("SimpleErrorPlugin");
+    } finally {
+      await client.suspend();
+    }
+  });
+});

packages/browser/test/BrowserExceptionlessClient.test.ts

@@ -194,7 +194,7 @@ export class EventBuilder {
     return this;
   }
 
-  public markAsCritical(critical: boolean): EventBuilder {
+  public markAsCritical(critical: boolean = true): EventBuilder {
     if (critical) {
       this.addTags("Critical");
     }

packages/core/src/EventBuilder.ts

@@ -0,0 +1,113 @@
+import { describe, expect, test } from "vitest";
+
+import { Configuration } from "../src/configuration/Configuration.js";
+import { ExceptionlessClient } from "../src/ExceptionlessClient.js";
+import { KnownEventDataKeys } from "../src/models/Event.js";
+
+describe("documentation examples", () => {
+  test("should configure production privacy and self-hosted endpoints", () => {
+    const config = new Configuration();
+
+    config.apiKey = "UNIT_TEST_API_KEY";
+    config.serverUrl = "https://collector.example.com";
+    config.configServerUrl = "https://config.example.com";
+    config.heartbeatServerUrl = "https://heartbeat.example.com";
+    config.version = "1.2.3";
+    config.defaultTags.push("core", "production");
+    config.addDataExclusions("authorization", "cookie", "password", "secret", "set-cookie", "token");
+    config.includePrivateInformation = false;
+
+    expect(config.isValid).toBe(true);
+    expect(config.serverUrl).toBe("https://collector.example.com");
+    expect(config.configServerUrl).toBe("https://config.example.com");
+    expect(config.heartbeatServerUrl).toBe("https://heartbeat.example.com");
+    expect(config.version).toBe("1.2.3");
+    expect(config.defaultTags).toEqual(["core", "production"]);
+    expect(config.dataExclusions).toEqual(["authorization", "cookie", "password", "secret", "set-cookie", "token"]);
+    expect(config.includeCookies).toBe(false);
+    expect(config.includeHeaders).toBe(false);
+    expect(config.includeIpAddress).toBe(false);
+    expect(config.includePostData).toBe(false);
+    expect(config.includeQueryString).toBe(false);
+  });
+
+  test("should build documented enriched exception events", () => {
+    const client = new ExceptionlessClient();
+    client.config.apiKey = "UNIT_TEST_API_KEY";
+    client.config.addDataExclusions("creditCardNumber");
+
+    const error = new Error("Unable to create order from quote");
+    const builder = client
+      .createException(error)
+      .setReferenceId("order-12345678")
+      .setProperty(
+        "Order",
+        {
+          id: "order-123",
+          quoteId: 123,
+          creditCardNumber: "4111111111111111"
+        },
+        4,
+        ["securityCode"]
+      )
+      .setProperty("Quote", 123)
+      .addTags("orders")
+      .markAsCritical()
+      .setGeo(43.595089, -88.444602)
+      .setUserIdentity("user-123", "Jane Doe")
+      .setUserDescription("jane@example.com", "The submit button returned a blank page.");
+
+    expect(builder.target.type).toBe("error");
+    expect(builder.target.reference_id).toBe("order-12345678");
+    expect(builder.target.tags).toEqual(["orders", "Critical"]);
+    expect(builder.target.geo).toBe("43.595089,-88.444602");
+    expect(builder.target.data?.Order).toEqual({ id: "order-123", quoteId: 123 });
+    expect(builder.target.data?.Quote).toBe(123);
+    expect(builder.target.data?.[KnownEventDataKeys.UserInfo]).toEqual({ identity: "user-123", name: "Jane Doe" });
+    expect(builder.target.data?.[KnownEventDataKeys.UserDescription]).toEqual({
+      email_address: "jane@example.com",
+      description: "The submit button returned a blank page."
+    });
+  });
+
+  test("should cancel events from documented runtime configuration plugins", async () => {
+    const client = new ExceptionlessClient();
+    client.config.apiKey = "UNIT_TEST_API_KEY";
+    client.config.settings["enableCheckoutEvents"] = "false";
+
+    client.config.addPlugin("CheckoutEventToggle", 100, (context) => {
+      const enabled = context.client.config.settings["enableCheckoutEvents"];
+
+      if (context.event.source === "checkout" && enabled === "false") {
+        context.cancelled = true;
+      }
+
+      return Promise.resolve();
+    });
+
+    const context = await client.createLog("checkout", "Checkout opened", "info").submit();
+
+    expect(context.cancelled).toBe(true);
+  });
+
+  test("should support documented session startup configuration", async () => {
+    const client = new ExceptionlessClient();
+
+    await client.startup((config) => {
+      config.apiKey = "UNIT_TEST_API_KEY";
+      config.setUserIdentity("user-123", "Jane Doe");
+      config.useSessions(true, 60000, true);
+      config.updateSettingsWhenIdleInterval = -1;
+    });
+
+    try {
+      const context = await client.submitSessionStart();
+
+      expect(client.config.sessionsEnabled).toBe(true);
+      expect(client.config.currentSessionIdentifier).toMatch(/^[0-9a-f]{32}$/);
+      expect(context.event.reference_id).toBe(client.config.currentSessionIdentifier);
+    } finally {
+      await client.suspend();
+    }
+  });
+});