Flagmint SDK Tester

A standalone tool for testing Flagmint's SDK protocol without writing code

Built for QA engineers, demos, and debugging

📋 Overview

This app connects directly to your Flagmint API using the raw wire protocol (WebSocket or HTTP long-polling). It does not use any Flagmint SDK — this is intentional, so you're testing the server contract, not the SDK's interpretation of it.

Perfect for:

✅ QA testing and validation
🐛 Debugging feature flag behavior
🎯 Testing targeting rules and context evaluation
🔄 Verifying real-time updates
📊 Comparing WebSocket vs long-polling transport

🚀 Quick Start

Prerequisites

Option A: Node.js 16+ and npm
Option B: Docker and Docker Compose
A Flagmint API instance (local or remote)
A valid SDK key from your Flagmint environment

Installation

Option 1: Local Development (Node.js)

# Clone or download this repository
cd flagmint-sdk-tester

# Install dependencies
npm install

# Start the development server
npm run dev

Open http://localhost:5173 in your browser, paste your SDK key, and connect!

Option 2: Docker (Recommended for Consistency)

Using Docker Compose (Easiest):

# Development mode (with hot reload)
docker-compose up dev

# Production mode (optimized build)
docker-compose up prod

Using Docker directly:

# Development mode
docker build --target development -t flagmint-sdk-tester:dev .
docker run -p 5173:5173 -v $(pwd):/app -v /app/node_modules flagmint-sdk-tester:dev

# Production mode
docker build --target production -t flagmint-sdk-tester:prod .
docker run -p 3000:3000 flagmint-sdk-tester:prod

Access the application:

Development: http://localhost:5173
Production: http://localhost:3000

Build for Production (Local)

npm run build
npm run preview

✨ Features

🔌 Connection Management

Dual Transport Support — Switch between WebSocket and HTTP long-polling
Connection Status — Real-time visual indicators for connection state
Auto-reconnect — Graceful handling of disconnections

🎯 Context Evaluation

Visual Context Builder — Add/remove key-value pairs via UI
Context Presets — Quick setups for common scenarios:
- Simple User — Basic { kind: 'user', key: '...' } context
- Multi-Context — Complex { kind: 'multi', user: {...}, organization: {...} } structure
- Empty — No context (tests default evaluation paths)
Nested Context Support — Use dot notation (e.g., user.key, organization.plan)
Type Inference — Automatically converts true, false, and numeric strings

🚩 Flag Display

Live Flag Values — See all flags with current values
Type Badges — Visual indicators for boolean, string, number, JSON, and null types
Real-Time Updates — Watch flags change instantly when modified in dashboard
Change History — Expand any flag to see its value history over time
Flag Search — Filter flags by name for large projects

📡 Protocol Logging

Message Inspector — View raw WebSocket messages
Connection Events — Track connect, disconnect, and error events
Debug Mode — Toggle verbose logging for troubleshooting
Auto-scroll — Automatically follows latest log entries

📖 Usage

Basic Workflow

Configure Connection
- Enter your API URL (e.g., http://localhost:3000)
- Paste your SDK key
- Choose transport: WebSocket (recommended) or long-polling
Set Up Context
- Use a preset or manually add context fields
- Example user context:
```
kind: user
key: test-user-123
country: US
plan: pro
```
Connect & Test
- Click "Connect" — connection status will turn green
- Click "Send Context" to evaluate flags with your context
- All matching flags will appear in the Flags tab
Verify Real-Time Updates
- Open Flagmint dashboard in another tab
- Toggle a flag value or targeting rule
- Watch the tester update instantly (WebSocket)

Testing Scenarios

Test User Targeting

Context:
  kind: user
  key: alice@example.com
  email: alice@example.com
  plan: enterprise

Verify flags target based on email domain or plan level.

Test Multi-Context Evaluation

Context:
  kind: multi
  user.kind: user
  user.key: alice@example.com
  organization.kind: organization
  organization.key: acme-corp
  organization.plan: enterprise

Verify organization-level flags override user-level defaults.

Test Empty Context

Context: (empty)

Verify default fallback values are returned correctly.

QA Testing Checklist

Flag evaluates with correct default value
Flag respects user targeting rules
Flag respects multi-context targeting
Flag updates in real-time when changed in dashboard
WebSocket connection is stable (no disconnects)
Long-polling fallback works correctly
Empty context returns expected defaults
Custom context attributes are evaluated correctly
Change history accurately tracks flag value changes

🏗️ Project Structure

flagmint-sdk-tester/
├── src/
│   ├── main.jsx         # React entry point
│   ├── App.jsx          # Main app component (UI, state management)
│   ├── connection.js    # Flagmint protocol client (WebSocket + long-polling)
│   └── helpers.js       # Utilities (type helpers, presets, context builder)
├── index.html           # HTML template
├── package.json         # Dependencies and scripts
├── vite.config.js       # Vite configuration
└── README.md            # This file

Key Files

connection.js — Raw protocol implementation. Handles WebSocket connections, long-polling, message parsing, and keep-alive pings.
helpers.js — Context building logic, type detection, and preset configurations.
App.jsx — Complete UI with connection panel, context builder, flag viewer, and log inspector.

🔧 Configuration

API URL

Default: http://localhost:3000

Update in the UI or set via localStorage:

localStorage.setItem('fm_tester_url', 'https://your-api.com');

SDK Key

Stored securely in localStorage (input type=password). Never committed to version control.

CORS Configuration

If your Flagmint API runs on a different origin, ensure CORS allows:

Access-Control-Allow-Origin: http://localhost:5173
Access-Control-Allow-Methods: POST, GET, OPTIONS
Access-Control-Allow-Headers: Content-Type, Authorization

🛠️ Tech Stack

React 19 — UI framework
Vite — Build tool and dev server
WebSocket API — Real-time communication
Fetch API — Long-polling fallback
Local Storage — Persistent configuration

No external dependencies for networking or UI — pure browser APIs.

🐛 Troubleshooting

Connection Fails

✅ Verify API URL is correct and reachable
✅ Check API key is valid for the environment
✅ Ensure API is running and healthy
✅ Check CORS configuration (see browser console for errors)

No Flags Appear

✅ Verify SDK key has access to flags
✅ Check context matches targeting rules
✅ Try empty context to see default values
✅ Check Protocol Log tab for server responses

WebSocket Disconnects

✅ Check API WebSocket endpoint is stable
✅ Try long-polling transport as fallback
✅ Verify no firewall/proxy blocking WebSocket connections
✅ Check API logs for errors

Wrong Flag Values

✅ Verify context structure matches expected format
✅ Check targeting rules in Flagmint dashboard
✅ Review change history to see if value recently updated
✅ Enable Debug mode in Protocol Log to see evaluation details

🤝 Contributing

This is a testing tool for Flagmint SDK validation. Contributions welcome!

Fork the repository
Create a feature branch (git checkout -b feature/improvement)
Commit your changes (git commit -am 'Add new feature')
Push to the branch (git push origin feature/improvement)
Open a Pull Request

📄 License

MIT License - see LICENSE file for details

🔗 Related

Made with 💜 for the Flagmint community

Name		Name	Last commit message	Last commit date
Latest commit History 5 Commits
src		src
.dockerignore		.dockerignore
.gitignore		.gitignore
Dockerfile		Dockerfile
README.md		README.md
docker-compose.yml		docker-compose.yml
index.html		index.html
package-lock.json		package-lock.json
package.json		package.json
vite.config.js		vite.config.js

Folders and files

Latest commit

History

Repository files navigation