golib/socket/TESTING.md

Testing Documentation

Comprehensive testing guide for the github.com/nabbar/golib/socket package core interfaces and types using BDD methodology with Ginkgo v2 and Gomega.

---

Table of Contents

• Overview
• Test Architecture
• Test Statistics
• Framework & Tools
• Quick Launch
• Coverage
  • Coverage Report
  • Thread Safety Assurance
• Performance
  • Performance Report
  • Test Conditions
  • Performance Limitations
• Test Writing
  • File Organization
  • Test Templates
  • Running New Tests
  • Helper Functions
  • Benchmark Template
  • Best Practices
• Troubleshooting
• Reporting Bugs & Vulnerabilities

---

Overview

Test Plan

This test suite provides comprehensive validation of the socket package core functionality following ISTQB principles. It focuses on validating the error handling, state management, and constant values through:

1. Functional Testing: Verification of ErrorFilter and ConnState.String()
2. Constant Validation: Testing of all connection state constants
3. Value Testing: Verification of DefaultBufferSize and EOL constants
4. Boundary Testing: Edge cases for error filtering and state strings
5. Concurrency Testing: Thread-safe concurrent operations validation
6. Performance Testing: Benchmarking of critical functions

Test Completeness

Quality Indicators:

• Code Coverage: 100.0% of statements (target: >80%)
• Race Conditions: 0 detected across all scenarios
• Flakiness: 0 flaky tests detected

Test Distribution:

• ✅ 62 specifications covering all functionality
• ✅ 200+ assertions validating behavior
• ✅ 13 example tests demonstrating usage patterns
• ✅ 4 performance benchmarks measuring key metrics
• ✅ 7 test files organized by functional area
• ✅ Zero flaky tests - all tests are deterministic

---

Test Architecture

Test Matrix

Category	Files	Specs	Coverage	Priority	Dependencies
Basic Tests	basic_test.go	23	100%	Critical	None
Benchmarks	benchmark_test.go	4	N/A	Medium	Basic
Edge Cases	edge_cases_test.go	23	100%	High	Basic
Concurrency	concurrent_test.go	9	100%	Critical	Basic
Helpers	helper_test.go	N/A	N/A	Low	All
Examples	example_test.go	13	N/A	High	All

Detailed Test Inventory

Test ID Pattern by File:

• TC-BS-xxx: Basic tests (basic_test.go)
• TC-BM-xxx: Benchmark tests (benchmark_test.go)
• TC-EC-xxx: Edge case tests (edge_cases_test.go)
• TC-CC-xxx: Concurrent tests (concurrent_test.go)

Test ID	File	Use Case	Priority	Expected Outcome
TC-BS-001	basic_test.go	DefaultBufferSize: Validate 32KB constant	Critical	Constant equals 32*1024
TC-BS-002	basic_test.go	EOL: Validate newline character	Critical	Constant equals '\n'
TC-BS-003	basic_test.go	ErrorFilter(nil): Nil error handling	Critical	Returns nil
TC-BS-004	basic_test.go	ErrorFilter(closed): Closed connection filter	Critical	Returns nil for closed errors
TC-BS-005	basic_test.go	ErrorFilter(normal): Normal error passthrough	Critical	Returns original error
TC-BS-006-022	basic_test.go	ConnState.String(): All state strings	Critical	Correct string for each state
TC-BS-023	basic_test.go	ConnState iteration: All states valid	High	No unknown states
TC-BM-001	benchmark_test.go	ErrorFilter benchmark: Various error types	Medium	Sub-microsecond performance
TC-BM-002	benchmark_test.go	ConnState.String benchmark: All states	Medium	Nanosecond performance
TC-BM-003	benchmark_test.go	Error lifecycle benchmark: Real-world scenario	Medium	Consistent performance
TC-BM-004	benchmark_test.go	State tracking benchmark: Overhead measurement	Medium	Minimal overhead
TC-EC-001-023	edge_cases_test.go	Edge cases: Complex errors, boundaries	High	Correct behavior at boundaries
TC-CC-001-009	concurrent_test.go	Concurrent operations: Thread safety	Critical	Zero race conditions

---

Test Statistics

Latest Test Run Results:

Total Specs:         62
Passed:              62
Failed:              0
Skipped:             0
Execution Time:      ~0.046 seconds
Coverage:            100.0%
Race Conditions:     0

Test Distribution:

Test Category	Count	Coverage
Basic Functionality	23	100%
Edge Cases	23	100%
Concurrency	9	100%
Performance	4	N/A
Examples	13	N/A

---

Framework & Tools

Testing Frameworks

Ginkgo v2 - BDD Testing Framework

Why Ginkgo over standard Go testing:

• ✅ Hierarchical organization: Describe, Context, It for clear test structure
• ✅ Better readability: Tests read like specifications
• ✅ Rich lifecycle hooks: BeforeEach, AfterEach for setup/teardown
• ✅ Async testing: Eventually, Consistently for concurrent behavior
• ✅ Parallel execution: Built-in support for concurrent test runs

Gomega - Matcher Library

Advantages:

• ✅ Expressive matchers: Equal, BeNumerically, HaveOccurred
• ✅ Clear failures: Detailed error messages
• ✅ Async assertions: Eventually polls for state changes

gmeasure - Performance Measurement

Used for benchmarking throughput and latency within the BDD suite.

Testing Concepts & Standards

ISTQB Alignment

This test suite follows ISTQB (International Software Testing Qualifications Board) principles:

1. Test Levels (ISTQB Foundation Level):

   • Unit Testing: Individual functions (ErrorFilter, ConnState.String)
   • Integration Testing: Component interactions (concurrent operations)

2. Test Types (ISTQB Advanced Level):

   • Functional Testing: Verify behavior meets specifications
   • Non-Functional Testing: Performance, concurrency, memory usage
   • Structural Testing: Code coverage

3. Test Design Techniques:

   • Equivalence Partitioning: Nil errors vs closed errors vs normal errors
   • Boundary Value Analysis: State enum boundaries, unknown states
   • Error Guessing: Concurrent access patterns

---

Quick Launch

Prerequisites

# Install Go 1.18 or later
go version  # Should be >= 1.18

# No additional tools required (Ginkgo/Gomega vendored)

Running Tests

# Quick test
go test

# Verbose output
go test -v

# With coverage
go test -cover

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

# Race detection (requires CGO)
CGO_ENABLED=1 go test -race

# Run examples
go test -v -run Example

Expected Output

$ go test -v

Running Suite: Socket Package Suite
====================================
Random Seed: 1766487880

Will run 62 of 62 specs

••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••

Ran 62 of 62 Specs in 0.046 seconds
SUCCESS! -- 62 Passed | 0 Failed | 0 Pending | 0 Skipped
--- PASS: TestSocket (0.05s)
=== RUN   ExampleConnState
--- PASS: ExampleConnState (0.00s)
[... 12 more examples ...]
PASS
coverage: 100.0% of statements
ok      github.com/nabbar/golib/socket  0.089s

---

Coverage

Coverage Report

Overall Coverage: 100.0% ✅ (Target: >80%)

Coverage by File:

File	Coverage	Statements	Covered	Missed
interface.go	100%	15	15	0
context.go	N/A	0	0	0

Functions:

Function	Coverage	Lines
ConnState.String()	100%	24
ErrorFilter()	100%	7

Why 100% is Achieved:

• ✅ All code paths exercised
• ✅ All branches tested
• ✅ All edge cases covered
• ✅ Unknown state tested
• ✅ Nil error tested
• ✅ Closed connection error tested
• ✅ Normal errors tested

How to Generate:

# Generate coverage
go test -coverprofile=coverage.out

# View in terminal
go tool cover -func=coverage.out

# Generate HTML report
go tool cover -html=coverage.out -o coverage.html

# Open in browser
open coverage.html  # macOS
xdg-open coverage.html  # Linux

Thread Safety Assurance

Race Detector Results: 0 races ✅

$ CGO_ENABLED=1 go test -race

Running Suite: Socket Package Suite
====================================
Will run 62 of 62 specs

••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••

Ran 62 of 62 Specs in 0.089 seconds
SUCCESS! -- 62 Passed | 0 Failed | 0 Pending | 0 Skipped

PASS
ok      github.com/nabbar/golib/socket  1.123s

Why Thread-Safe:

• ✅ No shared state: All functions are stateless
• ✅ Read-only operations: String() and ErrorFilter() only read
• ✅ Pure functions: No side effects
• ✅ Constant values: DefaultBufferSize and EOL are constants

Verified Thread-Safe:

• ConnState.String() can be called concurrently (tested with 1000 goroutines)
• ErrorFilter() can be called concurrently (tested with 1000 goroutines)
• All constants are immutable

---

Performance

Performance Report

Function Performance:

Function	Time/op	Notes
ConnState.String()	<10ns	Switch statement, very fast
ErrorFilter(nil)	<5ns	Early return
ErrorFilter(closed)	<50ns	String contains check
ErrorFilter(other)	<50ns	String contains check

Benchmark Results (from gmeasure):

ErrorFilter operations
====================================================================
Name                               | N     | Min | Median | Mean | Max
Normal error [duration]            | 10000 | 0s  | 0s     | 0s   | 0s
Nil error [duration]               | 10000 | 0s  | 0s     | 0s   | 100µs
Closed connection error [duration] | 10000 | 0s  | 0s     | 0s   | 200µs

ConnState String conversion
====================================================================
Name                             | N     | Min | Median | Mean | Max
Dial Connection [duration]       | 10000 | 0s  | 0s     | 0s   | 0s
New Connection [duration]        | 10000 | 0s  | 0s     | 0s   | 0s
[... all states < 1µs ...]

Connection lifecycle error handling
====================================================================
Name                       | N    | Min | Median | Mean | Max
error-lifecycle [duration] | 1000 | 0s  | 0s     | 0s   | 0s

State tracking overhead
====================================================================
Name                      | N    | Min | Median | Mean | Max
state-tracking [duration] | 1000 | 0s  | 0s     | 0s   | 0s

Key Observations:

• Zero allocations: All functions are allocation-free
• Nanosecond performance: Suitable for hot paths
• Consistent performance: No performance variance

Test Conditions

Test Environment:

• Hardware: Varies (local development machines, CI servers)
• OS: Linux, Darwin, Windows
• Go Version: 1.18 through 1.25
• CPU: Multi-core (benchmarks run on single core)

Test Isolation:

• Each test is independent
• No shared state between tests
• No test order dependencies
• Deterministic results

Performance Limitations

Why Minimal Benchmarks:

1. Simple Functions: ConnState.String() and ErrorFilter() are trivial
2. Negligible Overhead: <100ns per call
3. Not a Bottleneck: Never performance-critical in real applications
4. Zero Allocations: No memory optimization needed

Real Performance:

• Actual performance determined by protocol implementations
• See subpackage documentation for detailed benchmarks:
  • client/tcp/TESTING.md
  • server/tcp/TESTING.md
  • client/udp/TESTING.md
  • server/udp/TESTING.md

---

Test Writing

File Organization

socket/
├── suite_test.go           # Test suite entry point (Ginkgo suite setup)
├── basic_test.go           # Basic tests for constants and functions (23 specs)
├── benchmark_test.go       # Performance benchmarks with gmeasure (4 experiments)
├── edge_cases_test.go      # Edge cases and boundary tests (23 specs)
├── concurrent_test.go      # Concurrent safety tests (9 specs)
├── helper_test.go          # Shared test helpers and utilities
└── example_test.go         # Runnable examples for GoDoc (13 examples)

File Purpose Alignment:

File	Primary Responsibility	Unique Scope	Justification
suite_test.go	Test suite bootstrap	Ginkgo suite initialization only	Required entry point for BDD tests
basic_test.go	Core functionality	ErrorFilter, ConnState, constants	Unit tests for core package functions
benchmark_test.go	Performance metrics	gmeasure experiments	Non-functional performance validation
edge_cases_test.go	Boundary & error cases	Complex errors, boundaries	Negative testing and boundary value analysis
concurrent_test.go	Thread-safety	Race detection, concurrent patterns	Validates thread-safety guarantees
helper_test.go	Test infrastructure	Shared utilities	Test support (not executable tests)
example_test.go	Documentation	Runnable GoDoc examples	Documentation via executable examples

Test Templates

Basic Test Structure:

package socket_test

import (
    . "github.com/onsi/ginkgo/v2"
    . "github.com/onsi/gomega"
    
    libsck "github.com/nabbar/golib/socket"
)

var _ = Describe("Feature", func() {
    Context("specific scenario", func() {
        It("[TC-XX-001] should behave correctly", func() {
            // Arrange
            input := setupInput()
            
            // Act
            result := libsck.Feature(input)
            
            // Assert
            Expect(result).To(Equal(expected))
        })
    })
})

Example Test Structure:

package socket_test

import (
    "fmt"
    
    libsck "github.com/nabbar/golib/socket"
)

// ExampleFeature demonstrates feature usage
func ExampleFeature() {
    // Setup
    
    // Usage
    result := libsck.Feature()
    
    // Display result
    fmt.Println(result)
    
    // Output:
    // expected output
}

Running New Tests

# Focus on specific test
go test -ginkgo.focus="should behave correctly" -v

# Run specific test file
go test -v -run TestSocket

# Run specific example
go test -run ExampleFeature -v

Helper Functions

Test Utilities (helper_test.go):

Currently minimal, ready for future utilities as package grows.

Benchmark Template

gmeasure Experiment Pattern:

It("[TC-BM-XXX] should benchmark operation", func() {
    experiment := gmeasure.NewExperiment("Operation name")
    AddReportEntry(experiment.Name, experiment)

    experiment.SampleDuration("Test case", func(idx int) {
        // Test code here
    }, gmeasure.SamplingConfig{N: 1000, Duration: 0})
})

Best Practices

✅ DO

Write Clear Test Names:

// ✅ Good: Descriptive with test ID
It("[TC-BS-003] should return nil for nil error", func() {
    // Test implementation
})

Use Gomega Matchers:

// ✅ Good: Expressive assertions
Expect(result).To(BeNil())
Expect(value).To(Equal(expected))
Expect(state.String()).To(ContainSubstring("Connection"))

Test All Branches:

// ✅ Good: All states covered
states := []libsck.ConnState{
    libsck.ConnectionDial,
    libsck.ConnectionNew,
    // ... all states ...
    libsck.ConnState(255), // Unknown
}

❌ DON'T

Don't Skip Concurrent Tests:

// ❌ Bad: Skipping race detection
It("concurrent test", func() {
    Skip("TODO: add race detection")
})

// ✅ Good: Use defer GinkgoRecover()
It("concurrent test", func() {
    var wg sync.WaitGroup
    for i := 0; i < 100; i++ {
        wg.Add(1)
        go func() {
            defer GinkgoRecover()
            defer wg.Done()
            // Test code
        }()
    }
    wg.Wait()
})

---

Troubleshooting

Common Issues

1. Tests Pass Locally But Fail in CI

Problem: Platform-specific behavior differences

Solution: This package is platform-independent. If tests fail in CI:

• Check Go version compatibility
• Verify Ginkgo/Gomega are properly vendored
• Review CI environment setup

2. Coverage Not 100%

Problem: Missing test cases

Solution:

# View uncovered lines
go tool cover -html=coverage.out

# Identify missing tests
# Add tests for uncovered branches

3. Race Conditions Detected

Problem: Concurrent access without proper synchronization

Solution:

• Add defer GinkgoRecover() in all goroutines
• Use sync primitives (WaitGroup, Mutex)
• Use atomic operations for shared state

Debug Techniques

1. Verbose Output:

go test -v

2. Focus on Specific Test:

go test -ginkgo.focus="TC-BS-003"

3. Check Coverage:

go test -coverprofile=coverage.out
go tool cover -html=coverage.out

4. Race Detection:

CGO_ENABLED=1 go test -race -v

Getting Help

GitHub Issues: github.com/nabbar/golib/issues

Documentation:

• README.md
• doc.go
• GoDoc

---

Reporting Bugs & Vulnerabilities

Bug Report Template

When reporting a bug in the test suite or the socket package, please use this template:

**Title**: [BUG] Brief description of the bug

**Description**:
[A clear and concise description of what the bug is.]

**Steps to Reproduce:**
1. [First step]
2. [Second step]
3. [...]

**Expected Behavior**:
[A clear and concise description of what you expected to happen]

**Actual Behavior**:
[What actually happened]

**Code Example**:
[Minimal reproducible example]

**Test Case** (if applicable):
[Paste full test output with -v flag]

**Environment**:
- Go version: `go version`
- OS: Linux/macOS/Windows
- Architecture: amd64/arm64
- Package version: vX.Y.Z or commit hash

**Additional Context**:
[Any other relevant information]

**Logs/Error Messages**:
[Paste error messages or stack traces here]

**Possible Fix:**
[If you have suggestions]

Security Vulnerability Template

⚠️ IMPORTANT: For security vulnerabilities, please DO NOT create a public issue.

Instead, report privately via:

1. GitHub Security Advisories (preferred)
2. Email to the maintainer (see footer)

Vulnerability Report Template:

**Vulnerability Type:**
[e.g., Overflow, Race Condition, Memory Leak, Denial of Service]

**Severity:**
[Critical / High / Medium / Low]

**Affected Component:**
[e.g., interface.go, context.go, specific function]

**Affected Versions**:
[e.g., v1.0.0 - v1.2.3]

**Vulnerability Description:**
[Detailed description of the security issue]

**Attack Scenario**:
1. Attacker does X
2. System responds with Y
3. Attacker exploits Z

**Proof of Concept:**
[Minimal code to reproduce the vulnerability]
[DO NOT include actual exploit code]

**Impact**:
- Confidentiality: [High / Medium / Low]
- Integrity: [High / Medium / Low]
- Availability: [High / Medium / Low]

**Proposed Fix** (if known):
[Suggested approach to fix the vulnerability]

**CVE Request**:
[Yes / No / Unknown]

**Coordinated Disclosure**:
[Willing to work with maintainers on disclosure timeline]

Issue Labels

When creating GitHub issues, use these labels:

• bug: Something isn't working
• enhancement: New feature or request
• documentation: Improvements to docs
• performance: Performance issues
• test: Test-related issues
• security: Security vulnerability (private)
• help wanted: Community help appreciated
• good first issue: Good for newcomers

Reporting Guidelines

Before Reporting:

1. ✅ Search existing issues to avoid duplicates
2. ✅ Verify the bug with the latest version
3. ✅ Run tests with -race detector
4. ✅ Check if it's a test issue or package issue
5. ✅ Collect all relevant logs and outputs

What to Include:

• Complete test output (use -v flag)
• Go version (go version)
• OS and architecture (go env GOOS GOARCH)
• Race detector output (if applicable)
• Coverage report (if relevant)

Response Time:

• Bugs: Typically reviewed within 48 hours
• Security: Acknowledged within 24 hours
• Enhancements: Reviewed as time permits

---

AI Transparency

In compliance with EU AI Act Article 50.4: AI assistance was used for test generation, debugging, and documentation under human supervision. All tests are validated and reviewed by humans.

---

License

MIT License - See LICENSE file for details.

Copyright (c) 2025 Nicolas JUHEL

---

Test Suite Maintained by: Nicolas JUHEL Package: github.com/nabbar/golib/socket Framework: Ginkgo v2 + Gomega + gmeasure Coverage Target: 80%+ (Current: 100.0% ✅)