Prefer testing through public APIs

style.md

@@ -379,6 +379,28 @@ TEST_CASE("ArenaAllocator basic allocation") {
 }
 ```
 
+### Test Design Principles
+- **Prefer testing through public interfaces** - focus on observable behavior rather than implementation details
+- **Test the contract, not the implementation** - validate what the API promises to deliver
+- **Avoid testing private methods directly** - if private functionality needs testing, consider if it should be public or extracted
+- **Integration over isolation** - test components working together when practical
+- **Mock only external dependencies** - prefer real implementations for internal components
+```cpp
+// Good: Testing through public API
+TEST_CASE("Server accepts connections") {
+  auto config = Config::defaultConfig();
+  auto handler = std::make_unique<TestHandler>();
+  auto server = Server::create(config, std::move(handler));
+
+  // Test observable behavior - server can accept connections
+  auto result = connectToServer(server->getPort());
+  CHECK(result.connected);
+}
+
+// Avoid: Testing internal implementation details
+// TEST_CASE("Server creates epoll instance") { /* implementation detail */ }
+```
+
 ### Test Synchronization
 - **NEVER use timeouts** or sleep-based synchronization
 - **Deterministic synchronization only:**