# Examples Directory

This directory contains HTML examples demonstrating how to use the built Mocha Multiple Sessions TypeScript library in different scenarios.

## Available Examples

### 1. Basic ESM Example (`basic-esm.html`)
- **Purpose**: Demonstrates ES module usage
- **Library**: `../build/esm-bundled/mocha-multiple-sessions.mjs`
- **Features**: 
  - ES6 import syntax
  - Basic session creation and execution
  - Modern browser support

**Usage:**
```bash
# After building the library
npm run build

# Serve the examples (from project root)
npx serve . -p 3001

# Open http://localhost:3001/examples/basic-esm.html
```

### 2. Basic IIFE Example (`basic-iife.html`)
- **Purpose**: Demonstrates IIFE (global) usage
- **Library**: `../build/iife/mocha-multiple-sessions.js`
- **Features**:
  - Global `MochaMultipleSessions` object
  - No module bundler required
  - Compatible with older browsers

**Usage:**
```html
<script src="../build/iife/mocha-multiple-sessions.js"></script>
<script>
  const { testSession, runSession } = MochaMultipleSessions;
</script>
```

### 3. Advanced Features Example (`advanced-features.html`)
- **Purpose**: Comprehensive feature demonstration
- **Library**: `../build/iife/mocha-multiple-sessions.min.js` (minified)
- **Features**:
  - Multiple session management
  - SessionManager API
  - SessionBuilder pattern
  - Event system
  - Real-time logging

### 4. CDN Usage Example (`cdn-usage.html`)
- **Purpose**: Demonstrates CDN integration
- **Library**: CDN URL (when published)
- **Features**:
  - External CDN loading
  - Production-ready examples
  - Error handling demonstrations

## Running Examples

### Prerequisites
1. Build the library first:
   ```bash
   npm run build
   ```

2. Verify build outputs exist:
   ```
   build/
   ├── esm-bundled/mocha-multiple-sessions.mjs
   ├── iife/mocha-multiple-sessions.js
   ├── iife/mocha-multiple-sessions.min.js
   ├── cjs/mocha-multiple-sessions.js
   └── types/index.d.ts
   ```

### Method 1: Simple HTTP Server
```bash
# From project root
npx serve . -p 3001

# Open in browser:
# http://localhost:3001/examples/basic-esm.html
# http://localhost:3001/examples/basic-iife.html
# http://localhost:3001/examples/advanced-features.html
# http://localhost:3001/examples/cdn-usage.html
```

### Method 2: Python HTTP Server
```bash
# From project root
python -m http.server 3001

# Open same URLs as above
```

### Method 3: Live Server (VS Code)
1. Install "Live Server" extension
2. Right-click any HTML file
3. Select "Open with Live Server"

## Integration Patterns

### ESM Pattern (Modern)
```html
<script type="module">
  import { testSession, runSession } from '../build/esm-bundled/mocha-multiple-sessions.mjs';
  
  await testSession('my-tests', () => {
    describe('My Tests', () => {
      it('should work', () => {
        chai.expect(true).to.be.true;
      });
    });
  });
  
  const result = await runSession('my-tests');
</script>
```

### IIFE Pattern (Universal)
```html
<script src="../build/iife/mocha-multiple-sessions.min.js"></script>
<script>
  const { testSession, runSession } = MochaMultipleSessions;
  
  // Same usage as ESM
</script>
```

### CDN Pattern (Production)
```html
<script src="https://unpkg.com/mocha-multiple-sessions-ts@1.0.0/build/iife/mocha-multiple-sessions.min.js"></script>
<script>
  const { testSession, runSession } = MochaMultipleSessions;
</script>
```

## Common Setup

All examples include this basic setup:

```html
<!-- Required dependencies -->
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/mocha/10.2.0/mocha.min.css">
<script src="https://cdnjs.cloudflare.com/ajax/libs/mocha/10.2.0/mocha.min.js"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/chai/4.3.10/chai.min.js"></script>

<!-- Configure Mocha -->
<script>mocha.setup('bdd');</script>

<!-- Configure library -->
<script>
testSessionSetup({
  createMochaInstance: (sessionLabel) => {
    return new Mocha({
      ui: 'bdd',
      reporter: Mocha.reporters.HTML
    });
  },
  injectGlobals: (mochaInstance) => {
    mochaInstance.suite.emit('pre-require', window, null, mochaInstance);
    if (window.chai) {
      window.expect = window.chai.expect;
    }
  }
});
</script>
```

## Troubleshooting

### Library Not Loading
- Check that `npm run build` completed successfully
- Verify the file paths in HTML match actual build output
- Check browser console for loading errors

### Module Import Errors
- Ensure using `type="module"` for ESM imports
- Use relative paths (e.g., `../build/...`)
- Check CORS issues if serving from different domain

### Test Execution Issues
- Verify Mocha and Chai are loaded before the library
- Check that `mocha.setup('bdd')` is called
- Ensure `testSessionSetup()` is configured properly

### Browser Compatibility
- ESM examples require modern browsers (ES2015+)
- IIFE examples work in older browsers
- Use polyfills if needed for older browser support

## Contributing

To add new examples:

1. Create new HTML file in `examples/` directory
2. Follow existing naming convention
3. Include comprehensive comments
4. Test with both development and built library
5. Update this README with description
6. Add entry to main project documentation

## Next Steps

After running these examples:

1. **Development**: Use the TypeScript source with Vite dev server
2. **Production**: Use built files for deployment
3. **Testing**: Integrate with your existing test setup
4. **Customization**: Modify examples for your specific needs