website-htmx-rustelo-code/scripts/nav-test/README.md

# Navigation Test Scripts

This directory contains scripts for testing SPA navigation without requiring a browser. These scripts use the HTTP navigation test API to validate routes, test navigation sequences, and benchmark performance.

## Prerequisites

1. **Server with navigation testing API enabled**:
   ```bash
   just dev::with-nav-test
   # OR manually:
   ENABLE_NAV_TEST_API=true cargo leptos serve --features content-watcher
   ```

2. **Optional tools for better output**:
   ```bash
   # Install jq for JSON parsing
   brew install jq  # macOS
   apt install jq   # Ubuntu
   
   # Install bc for performance calculations  
   brew install bc  # macOS
   apt install bc   # Ubuntu
   ```

## Scripts

### 1. test-single-route.sh
Test individual route resolution.

```bash
# Test home route
./test-single-route.sh /

# Test services route  
./test-single-route.sh /services

# Test Spanish route
./test-single-route.sh /es/contactar
```

### 2. test-navigation-sequence.sh
Test navigation transitions between routes.

```bash
# Test navigation from home to services
./test-navigation-sequence.sh / /services

# Test cross-language navigation
./test-navigation-sequence.sh / /es
```

### 3. validate-all-routes.sh
Validate all configured routes in the system.

```bash
# Validate all routes
./validate-all-routes.sh
```

### 4. benchmark-route.sh
Benchmark route resolution performance.

```bash
# Benchmark home route (default 1000 iterations)
./benchmark-route.sh /

# Benchmark with custom iterations
./benchmark-route.sh /services 5000
```

### 5. full-test-suite.sh
Run comprehensive navigation test suite.

```bash
# Run all tests
./full-test-suite.sh
```

## Environment Variables

- **BASE_URL**: Server base URL (default: `http://localhost:3030`)
  ```bash
  BASE_URL=http://localhost:8080 ./test-single-route.sh /
  ```

## Integration with Just

These scripts are integrated with the justfile for easy access:

```bash
# Individual tests
just dev::nav-test-route /services
just dev::nav-test-sequence / /services
just dev::nav-test-validate
just dev::nav-test-bench /services

# Full suite
just dev::nav-test-all
```

## CI/CD Usage

For automated testing in CI/CD pipelines:

```bash
# Start server in background
ENABLE_NAV_TEST_API=true cargo leptos serve --features content-watcher &

# Wait for server startup
sleep 5

# Run quick validation
./validate-all-routes.sh

# Or run full suite
./full-test-suite.sh
```

## Troubleshooting

### Server Not Running
```
❌ Server not running at http://localhost:3030
💡 Start server with: just dev::with-nav-test
```

**Solution**: Start the server with navigation testing API enabled.

### Invalid Routes Found
```
❌ Invalid Routes:
  - /nonexistent (en): Route not found
```

**Solution**: Check your route configuration in `site/config/routes/` directory.

### Missing Dependencies
```
💡 Install jq for better output formatting: brew install jq
```

**Solution**: Install optional dependencies for enhanced output formatting.

## Output Examples

### Successful Route Test
```
🧭 Testing navigation to: /services
✅ Route test successful
📊 Route Information:
  Path: /services
  Component: ServicesPage
  Language: en
  Valid: true
  Resolution Time: 0.145ms
🎉 Navigation test completed successfully
```

### Navigation Sequence Test
```
🧭 Testing navigation sequence: / → /services
✅ Navigation test successful
📊 Navigation Information:
  From: / → /services
  Transition: valid
  From Component: HomePage
  To Component: ServicesPage
  Language: en
  Valid: true
🎉 Navigation sequence test completed successfully
```

### Performance Benchmark
```
🧭 Benchmarking route resolution: /services
✅ Benchmark completed
📊 Performance Metrics:
  Path: /services
  Component: ServicesPage
  Iterations: 1000
  Total Time: 125.43ms
  Average Time: 0.125ms
  Min Time: 0.089ms
  Max Time: 2.134ms
🚀 Excellent performance (< 0.1ms avg)
⚡ Requests per second: ~7968
```