A comprehensive testing skill for MQTT X applications, providing templates, scripts, and best practices for writing high-quality tests.

mqttx-testing/
├── SKILL.md                          # Main skill documentation
├── README.md                         # This file
├── assets/                           # Test templates
│   ├── unit-test.go.tmpl            # Unit test template
│   ├── integration-test.go.tmpl     # Integration test template
│   └── benchmark-test.go.tmpl       # Benchmark test template
├── scripts/                          # Automation scripts
│   └── run-tests.sh                 # Test execution script (executable)
└── references/                       # Reference documentation
    └── testing-best-practices.md    # Comprehensive testing guide

cat docs/skills/mqttx-testing/SKILL.md

The templates in assets/ provide starting points for different test types:

• unit-test.go.tmpl: Template for unit tests with table-driven approach
• integration-test.go.tmpl: Template for end-to-end integration tests
• benchmark-test.go.tmpl: Template for performance benchmarks

# Make script executable (if not already)
chmod +x docs/skills/mqttx-testing/scripts/run-tests.sh

# Run all tests
./docs/skills/mqttx-testing/scripts/run-tests.sh

# Run with options
./docs/skills/mqttx-testing/scripts/run-tests.sh --help

cat docs/skills/mqttx-testing/references/testing-best-practices.md

Provides:

• Table-driven test structure
• Setup and cleanup helpers
• Error handling tests
• Concurrent testing examples
• Mock objects
• Benchmark templates

Variables to replace:

• {{.PackageName}}: Package name (e.g., mqttx)
• {{.FeatureName}}: Feature being tested (e.g., Session)
• {{.TestCase1}}, {{.TestCase2}}: Test case names

Provides:

• End-to-end publish/subscribe tests
• Multi-session interaction tests
• Error recovery integration tests
• Persistence and restore tests
• Health check tests
• Message forwarding tests

Variables to replace:

• {{.PackageName}}: Package name
• {{.FeatureName}}: Feature being tested
• {{.BrokerAddress}}: MQTT broker address
• {{.Username}}: MQTT username
• {{.Password}}: MQTT password

Provides:

• Session creation benchmarks
• Message publish benchmarks
• QoS level comparison benchmarks
• Concurrent access benchmarks
• Store operation benchmarks
• Metrics recording benchmarks

Variables to replace:

• {{.PackageName}}: Package name
• {{.FeatureName}}: Feature being benchmarked

• Run unit tests with coverage
• Run tests with race detector
• Run integration tests
• Run benchmarks
• Generate HTML coverage reports
• Colorized output
• Configurable via command-line flags

# Show help
./docs/skills/mqttx-testing/scripts/run-tests.sh --help

# Run all unit tests with coverage
./docs/skills/mqttx-testing/scripts/run-tests.sh

# Run short tests only
./docs/skills/mqttx-testing/scripts/run-tests.sh -s

# Run with race detector
./docs/skills/mqttx-testing/scripts/run-tests.sh -r

# Run integration tests
./docs/skills/mqttx-testing/scripts/run-tests.sh -i

# Run benchmarks
./docs/skills/mqttx-testing/scripts/run-tests.sh -b

# Verbose output
./docs/skills/mqttx-testing/scripts/run-tests.sh -v

# Multiple options
./docs/skills/mqttx-testing/scripts/run-tests.sh -s -r -v

The references/testing-best-practices.md document covers:

1. Testing Strategy: Test pyramid, when to use each test type
2. Test Organization: File naming, test naming, table-driven tests
3. Mock Objects: Creating stubs for MQTT clients, brokers, storage
4. Concurrent Testing: Thread-safety testing, atomic operations
5. Race Detection: Using -race flag, writing race-free code
6. Benchmark Testing: Writing benchmarks, parallel benchmarks
7. Integration Testing: Setup/teardown, async operations
8. Code Coverage: Generating reports, coverage goals
9. Debugging: Logging, running single tests, debugging races
10. Common Pitfalls: Resource cleanup, error handling, flaky tests

cp docs/skills/mqttx-testing/assets/unit-test.go.tmpl session_feature_test.go

// Change:
package {{.PackageName}}

// To:
package mqttx

// Change:
func Test{{.FeatureName}}(t *testing.T)

// To:
func TestSessionPublish(t *testing.T)

Add your specific test cases to the table-driven test structure.

go test -v -run TestSessionPublish

# 1. Write tests first (TDD)
# 2. Run short tests during development
go test -short ./...

# 3. Run full tests before commit
go test ./...

# 4. Check coverage
go test -cover ./...

# 5. Run race detector
go test -race ./...

# 6. Run benchmarks for performance-critical changes
go test -bench=. -benchmem

# In CI pipeline
./docs/skills/mqttx-testing/scripts/run-tests.sh -r -v

# Generate coverage report
go test -coverprofile=coverage.out ./...
go tool cover -html=coverage.out -o coverage.html

# Upload coverage to codecov or similar

Coverage	Status	Action
80-100%	Excellent	Maintain
60-80%	Good	Improve critical paths
40-60%	Fair	Add more tests
0-40%	Poor	Urgent: Add comprehensive tests

tests := []struct {
    name    string
    input   interface{}
    want    interface{}
    wantErr error
}{
    // Test cases
}

for _, tt := range tests {
    t.Run(tt.name, func(t *testing.T) {
        // Test logic
    })
}

func TestFeature(t *testing.T) {
    // Setup
    manager := NewSessionManager()
    defer manager.Close()

    // Test logic
}

type mockClient struct {
    connected bool
    calls     int
}

func (m *mockClient) Method() {
    m.calls++
}

var wg sync.WaitGroup
for i := 0; i < 100; i++ {
    wg.Add(1)
    go func() {
        defer wg.Done()
        // Concurrent operation
    }()
}
wg.Wait()

received := make(chan *Message, 1)
go func() {
    // Async operation
}()

select {
case msg := <-received:
    // Verify message
case <-time.After(5 * time.Second):
    t.Fatal("Timeout")
}

• Run with -race to detect race conditions
• Increase timeouts for async operations
• Check for shared state between tests
• Use -count=100 to reproduce flaky tests

• Identify uncovered code: go tool cover -func=coverage.out | grep -v "100.0%"
• Add tests for error paths
• Test edge cases
• Test error recovery

• Use mutex or atomic operations for shared state
• Avoid goroutine leaks
• Properly synchronize channel operations
• Review concurrent access patterns

• MQTT X Documentation: /workspace/docs/
• Example Tests: /workspace/*_test.go
• Go Testing Package: https://pkg.go.dev/testing
• Race Detector: https://go.dev/blog/race-detector

When adding new test patterns or templates:

1. Add template to assets/ directory
2. Document in SKILL.md
3. Add examples to references/testing-best-practices.md
4. Update this README

Same as MQTT X project.