Testing guide

This guide covers how to test your Facets web component locally, debug it with browser DevTools, and troubleshoot common issues.

Local Testing with index.html

Every component should include a test page. Create an index.html in your repository root:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>My Component - Test Page</title>
  <style>
    body { margin: 0; padding: 20px; font-family: sans-serif; }
    .note { background: #fff3cd; padding: 12px; border-radius: 4px; margin-bottom: 16px; }
  </style>
</head>
<body>
  <h1>My Component - Local Test</h1>
  <div class="note">
    <strong>Note:</strong> API calls require a valid session cookie from Facets.
    To test with real data, use the API proxy method described below.
  </div>
  <my-component></my-component>
  <script src="my-component.js"></script>
</body>
</html>

Open it directly in a browser:

open index.html        # macOS
xdg-open index.html    # Linux

This lets you verify that:

The component renders without JavaScript errors
The Shadow DOM structure is correct
Styles are applied properly
Event listeners are wired up

API calls will fail (no session cookie) but you can verify the UI structure, loading states, and error handling.

Testing with API Proxy

To test with real API data locally, set up a reverse proxy that forwards API calls to your Facets instance:

Option 1: Simple Python Proxy

Create a proxy.py file:

from http.server import HTTPServer, SimpleHTTPRequestHandler
import urllib.request
import os

FACETS_URL = os.environ.get("FACETS_URL", "https://your-instance.console.facets.cloud")
FACETS_COOKIE = os.environ.get("FACETS_COOKIE", "")

class ProxyHandler(SimpleHTTPRequestHandler):
    def do_GET(self):
        if self.path.startswith("/cc-ui/"):
            # Proxy API calls to Facets
            url = FACETS_URL + self.path
            req = urllib.request.Request(url)
            req.add_header("Cookie", FACETS_COOKIE)
            try:
                with urllib.request.urlopen(req) as resp:
                    self.send_response(resp.status)
                    self.send_header("Content-Type", resp.headers.get("Content-Type", "application/json"))
                    self.end_headers()
                    self.wfile.write(resp.read())
            except Exception as e:
                self.send_response(502)
                self.end_headers()
                self.wfile.write(str(e).encode())
        else:
            # Serve static files
            super().do_GET()

HTTPServer(("localhost", 8080), ProxyHandler).serve_forever()

Run it:

FACETS_URL="https://your-instance.console.facets.cloud" \
FACETS_COOKIE="your-session-cookie" \
python proxy.py

Then open http://localhost:8080/index.html.

Option 2: Using a Facets Dev Session

If you have access to a running Facets instance, you can test directly:

Deploy your component to GitHub Pages (or any HTTPS hosting)
Register it in Facets via Organization Settings > Web Components
Reload the Facets UI: your component appears in the sidebar. Click it to test with real data

This is the most accurate test because it uses real session cookies and the actual platform rendering environment.

Browser DevTools Debugging

Inspecting Shadow DOM

Open DevTools (F12 or Cmd+Option+I). In the Elements panel, expand your custom element
You'll see a #shadow-root (open) node -- expand it to see your component's DOM. You can edit styles and HTML directly in the inspector

Network Tab

Use the Network tab to verify API calls:

Check that requests go to relative paths (/cc-ui/v1/...)
Verify the session cookie is included in request headers
Check response status codes and body content

Console

Your component should log errors to the console. Check for:

JavaScript errors (red)
Failed network requests
customElements.define() conflicts (if the element name is already registered)

Debugging Tips

// Add temporary debug logging
async fetchData() {
  console.log('[MyComponent] Fetching data with filters:', this.filters);
  try {
    const response = await fetch('/cc-ui/v1/endpoint');
    console.log('[MyComponent] Response status:', response.status);
    const data = await response.json();
    console.log('[MyComponent] Data received:', data);
    // ...
  } catch (error) {
    console.error('[MyComponent] Fetch failed:', error);
  }
}

Setting Breakpoints

In the Sources tab:

Find your component file (it will be under the script URL)
Click on a line number to set a breakpoint
Interact with your component to trigger the code
Use the debugger to step through execution

Common Issues and Solutions

Component Not Rendering

Symptom: The sidebar shows nothing or a blank area.

Check	Fix
Console shows "custom element already defined"	Ensure your element name is unique across all registered components
Console shows "Failed to load script"	Verify the `remoteURL` is accessible (test with `curl`)
No errors at all	Check that `customElements.define()` is called at module scope, not inside a function

API Returns 401

Symptom: All API calls fail with 401 Unauthorized.

This means the session cookie is not being sent. Possible causes:

Testing outside the Facets platform (use the proxy method above)
Using absolute URLs instead of relative URLs
Session has expired -- user needs to log in again

Styles Not Applied

Symptom: Component renders but looks unstyled.

Check	Fix
Styles defined outside Shadow DOM	Move all `<style>` tags inside `this.shadowRoot.innerHTML`
Using `document.querySelector()`	Switch to `this.shadowRoot.querySelector()`
Trying to use external CSS files	Inline all styles in the Shadow DOM (external stylesheets don't cross the shadow boundary)

Component Shows Stale Data

Symptom: Data doesn't update after changes in Facets.

The .js file may be cached by the browser or CDN
Hard-refresh (Ctrl+Shift+R / Cmd+Shift+R) to clear cache
For persistent issues, add a cache-busting query parameter to your script URL during development

Deployment Workflow Fails

Symptom: GitHub Actions workflow fails.

Common causes:

Missing permissions block in workflow YAML
Pages not enabled in repository settings
Repository is private (GitHub Pages requires public repo on free plan, or Pro/Team/Enterprise)