# Testing Guide for homebridge-oto

## Build Status ✅

The project builds successfully with:
- ✅ Zero TypeScript errors
- ✅ Zero linting errors  
- ✅ All tests passing (3/3)

```bash
npm run build    # Compiles TypeScript → dist/
npm run lint     # Code quality checks
npm test         # Run Jest tests
npm run watch    # Watch mode for development
```

## Installation & Setup

### Option 1: Local Testing with Homebridge (Recommended)

1. **Install Homebridge** (if not already installed):
   ```bash
   npm install -g homebridge homebridge-config-ui-x
   ```

2. **Install the plugin locally**:
   ```bash
   cd C:\Users\jonna\Development\homebridge-oto
   npm install -g .
   ```
   This installs your local version globally for testing.

3. **Create a Homebridge config** at `~/.homebridge/config.json`:
   ```json
   {
     "bridge": {
       "name": "Homebridge",
       "username": "CC:22:3D:E3:CE:30",
       "port": 51826,
       "pin": "031-45-154"
     },
     "platforms": [
       {
         "platform": "Oto",
         "name": "Oto Sprinklers",
         "email": "your-oto-email@example.com",
         "password": "your-oto-password",
         "apiBaseUrl": "https://api.oto.com",
         "updateInterval": 30
       }
     ],
     "accessories": []
   }
   ```

4. **Start Homebridge**:
   ```bash
   homebridge
   ```

5. **Monitor the logs**:
   - Watch for "Discovering Oto devices..." message
   - Zone names should appear as accessories being added
   - Check for any authentication errors

### Option 2: Test with Homebridge Config UI

1. **Install Config UI X** (if not already):
   ```bash
   sudo npm install -g homebridge-config-ui-x
   ```

2. **Start Homebridge with Config UI**:
   ```bash
   homebridge -D
   ```

3. **Access the web interface** (usually http://localhost:8581)

4. **Search for and install the "oto" plugin** via the UI

5. **Configure your Oto credentials** through the web interface

## Manual Testing

### Test 1: API Client Initialization
```bash
npm test
```
**Expected output**: 3 passing tests

### Test 2: Build Verification
```bash
npm run build
```
**Expected**: No compilation errors, `dist/` folder generated

### Test 3: Code Quality
```bash
npm run lint
```
**Expected**: No linting errors

### Test 4: Development Watch Mode
```bash
npm run watch
```
**Expected**: Continuous compilation as you edit source files

## Integration Testing with HomeKit

Once the plugin is running in Homebridge:

1. **Open HomeKit app** on your iPhone/iPad/Mac
2. **Add Accessory** → Scan code or manually add
3. **Enter HomeKit setup code** from Homebridge config (default: `031-45-154`)
4. **Assign to room** and verify all zones appear as Valve accessories

## Troubleshooting

### Plugin not found
```bash
# Reinstall the plugin
npm install -g .
```

### Authentication fails
- Verify email and password are correct
- Test login in the Oto mobile app
- Check Homebridge logs for API errors

### Devices not appearing
- Ensure your Oto account has controllers configured
- Check that controllers are online in the Oto app
- Increase `updateInterval` if seeing rate limit errors

### Status not updating
- Default update interval is 30 seconds
- Reduce to 15-20 seconds for faster updates (10 second minimum)
- Check Homebridge logs for API errors

## Example Homebridge Log Output

```
[6/14/2026, 12:30:45 AM] [Oto] Initializing OtoPlatform
[6/14/2026, 12:30:45 AM] [Oto] Discovering Oto devices...
[6/14/2026, 12:30:46 AM] [Oto] Found 1 controller(s)
[6/14/2026, 12:30:46 AM] [Oto] Controller "Front Lawn" has 3 zone(s)
[6/14/2026, 12:30:46 AM] [Oto] Added accessory: Front Lawn - Zone 1
[6/14/2026, 12:30:46 AM] [Oto] Added accessory: Front Lawn - Zone 2
[6/14/2026, 12:30:46 AM] [Oto] Added accessory: Front Lawn - Zone 3
[6/14/2026, 12:30:46 AM] [Oto] Started periodic device discovery (30000ms)
```

## Testing Device Actions

Once accessories are in HomeKit:

1. **Turn on a zone**
   - Tap the valve in HomeKit
   - Should see "watering" indicator in Oto app
   - Check Homebridge logs for "Started watering..."

2. **Set watering duration**
   - Hold the valve accessory
   - Adjust duration (60-3600 seconds, default 600s)
   - Duration resets on zone restart

3. **Create automations**
   - Set zone to water at specific time
   - Create sensor-based triggers
   - Test manual on/off control

## Publishing

When ready to publish to npm:

```bash
# Update version in package.json
npm version patch  # or minor/major

# Run final build
npm run build
npm run lint
npm test

# Publish
npm publish
```

## Environment Requirements

- **Node.js**: 16+
- **npm**: 8+
- **Homebridge**: 1.4.0+
- **Oto account**: Valid account with controller(s)
- **Internet connection**: Required for API communication

## API Details

The plugin communicates with these Oto API endpoints:
- `POST /auth/login` - Authentication
- `GET /controllers` - List controllers
- `GET /controllers/{id}/zones` - List zones
- `GET /controllers/{id}/zones/{id}` - Get zone status
- `POST /controllers/{id}/zones/{id}/start` - Start zone
- `POST /controllers/{id}/zones/{id}/stop` - Stop zone

Token refresh happens automatically when expired (60 second buffer).