@ -29,7 +29,7 @@ type inMemoryRepo struct {
attempts [ ] * domain . SessionAttempt
}
// newInMemoryRepo is a test helper .
// newInMemoryRepo creates in-memory test doubles and deterministic fixtures .
func newInMemoryRepo ( ) * inMemoryRepo {
return & inMemoryRepo {
sessions : map [ string ] * domain . GameSession { } ,
@ -37,10 +37,10 @@ func newInMemoryRepo() *inMemoryRepo {
}
}
// EnsureSchema i s a test helper .
// EnsureSchema i nitializes schema state required before repository operations .
func ( r * inMemoryRepo ) EnsureSchema ( ctx context . Context ) error { return nil }
// CreateSession is a test helper .
// CreateSession persists a new entity in the in-memory repository .
func ( r * inMemoryRepo ) CreateSession ( ctx context . Context , session * domain . GameSession ) ( * domain . GameSession , error ) {
session . ID = "sess-1"
now := time . Now ( ) . UTC ( )
@ -51,7 +51,7 @@ func (r *inMemoryRepo) CreateSession(ctx context.Context, session *domain.GameSe
return & cp , nil
}
// GetSessionByID is a test helper .
// GetSessionByID retrieves data from the in-memory repository .
func ( r * inMemoryRepo ) GetSessionByID ( ctx context . Context , id string ) ( * domain . GameSession , error ) {
s , ok := r . sessions [ id ]
if ! ok {
@ -61,7 +61,7 @@ func (r *inMemoryRepo) GetSessionByID(ctx context.Context, id string) (*domain.G
return & cp , nil
}
// GetActiveSessionByPlayerID is a test helper .
// GetActiveSessionByPlayerID retrieves data from the in-memory repository .
func ( r * inMemoryRepo ) GetActiveSessionByPlayerID ( ctx context . Context , playerID string ) ( * domain . GameSession , error ) {
for _ , s := range r . sessions {
if s . PlayerID == playerID && s . Status == domain . StatusActive {
@ -72,7 +72,7 @@ func (r *inMemoryRepo) GetActiveSessionByPlayerID(ctx context.Context, playerID
return nil , domain . ErrSessionNotFound
}
// UpdateSession is a test helper .
// UpdateSession updates an existing entity in the in-memory repository .
func ( r * inMemoryRepo ) UpdateSession ( ctx context . Context , session * domain . GameSession ) ( * domain . GameSession , error ) {
cp := * session
cp . UpdatedAt = time . Now ( ) . UTC ( )
@ -80,17 +80,17 @@ func (r *inMemoryRepo) UpdateSession(ctx context.Context, session *domain.GameSe
return & cp , nil
}
// CreateAttempt is a test helper .
// CreateAttempt persists a new entity in the in-memory repository .
func ( r * inMemoryRepo ) CreateAttempt ( ctx context . Context , attempt * domain . SessionAttempt ) error {
cp := * attempt
r . attempts = append ( r . attempts , & cp )
return nil
}
// CreateEvent is a test helper .
// CreateEvent persists a new entity in the in-memory repository .
func ( r * inMemoryRepo ) CreateEvent ( ctx context . Context , event * domain . SessionEvent ) error { return nil }
// ListQuestionIDsForSession is a test helper .
// ListQuestionIDsForSession returns filtered collections from the in-memory repository .
func ( r * inMemoryRepo ) ListQuestionIDsForSession ( ctx context . Context , sessionID string ) ( [ ] string , error ) {
seen := map [ string ] bool { }
ids := make ( [ ] string , 0 )
@ -112,7 +112,7 @@ type fakeQuestionBank struct {
questions [ ] appsession . SessionQuestion
}
// GetRandomQuestion is a test helper .
// GetRandomQuestion retrieves data from the in-memory repository .
func ( f * fakeQuestionBank ) GetRandomQuestion (
ctx context . Context ,
exclusions [ ] string ,
@ -132,7 +132,7 @@ func (f *fakeQuestionBank) GetRandomQuestion(
return nil , domain . ErrSessionNotFound
}
// GetQuestionByID is a test helper .
// GetQuestionByID retrieves data from the in-memory repository .
func ( f * fakeQuestionBank ) GetQuestionByID ( ctx context . Context , id string ) ( * appsession . SessionQuestion , error ) {
for _ , q := range f . questions {
if q . ID == id {
@ -143,7 +143,7 @@ func (f *fakeQuestionBank) GetQuestionByID(ctx context.Context, id string) (*app
return nil , domain . ErrSessionNotFound
}
// ValidateAnswer is a test helper .
// ValidateAnswer supports validate answer test setup and assertions .
func ( f * fakeQuestionBank ) ValidateAnswer (
ctx context . Context ,
questionID , answer string ,
@ -157,7 +157,7 @@ func (f *fakeQuestionBank) ValidateAnswer(
// fakeUserClient returns a verified user profile for tests.
type fakeUserClient struct { }
// GetUserProfile is a test helper .
// GetUserProfile retrieves data from the in-memory repository .
func ( f * fakeUserClient ) GetUserProfile (
ctx context . Context ,
userID , bearerToken string ,
@ -175,7 +175,7 @@ type fakeStateStore struct {
locks map [ string ] bool
}
// newFakeStateStore is a test helper .
// newFakeStateStore creates in-memory test doubles and deterministic fixtures .
func newFakeStateStore ( ) * fakeStateStore {
return & fakeStateStore {
active : map [ string ] string { } ,
@ -183,38 +183,38 @@ func newFakeStateStore() *fakeStateStore {
}
}
// GetActiveSession is a test helper .
// GetActiveSession retrieves data from the in-memory repository .
func ( s * fakeStateStore ) GetActiveSession ( ctx context . Context , playerID string ) ( string , bool ) {
id , ok := s . active [ playerID ]
return id , ok
}
// SetActiveSession is a test helper .
// SetActiveSession stores ephemeral state in the fake cache or state store .
func ( s * fakeStateStore ) SetActiveSession ( ctx context . Context , playerID , sessionID string , ttl time . Duration ) error {
s . active [ playerID ] = sessionID
return nil
}
// ClearActiveSession is a test helper .
// ClearActiveSession removes ephemeral state from the fake cache or state store .
func ( s * fakeStateStore ) ClearActiveSession ( ctx context . Context , playerID string ) error {
delete ( s . active , playerID )
return nil
}
// SetTimer is a test helper .
// SetTimer stores ephemeral state in the fake cache or state store .
func ( s * fakeStateStore ) SetTimer ( ctx context . Context , sessionID string , expiresAt time . Time , ttl time . Duration ) error {
return nil
}
// GetTimer is a test helper .
// GetTimer retrieves data from the in-memory repository .
func ( s * fakeStateStore ) GetTimer ( ctx context . Context , sessionID string ) ( time . Time , bool ) {
return time . Time { } , false
}
// ClearTimer is a test helper .
// ClearTimer removes ephemeral state from the fake cache or state store .
func ( s * fakeStateStore ) ClearTimer ( ctx context . Context , sessionID string ) error { return nil }
// AcquireLock is a test helper .
// AcquireLock simulates distributed lock coordination for concurrent test flows .
func ( s * fakeStateStore ) AcquireLock ( ctx context . Context , sessionID string , ttl time . Duration ) bool {
if s . locks [ sessionID ] {
return false
@ -223,12 +223,12 @@ func (s *fakeStateStore) AcquireLock(ctx context.Context, sessionID string, ttl
return true
}
// ReleaseLock is a test helper .
// ReleaseLock simulates distributed lock coordination for concurrent test flows .
func ( s * fakeStateStore ) ReleaseLock ( ctx context . Context , sessionID string ) {
delete ( s . locks , sessionID )
}
// setupApp wires a test Fiber app with in-memory dependencies and auth middleware .
// setupApp wires the test application with mocked dependencies .
func setupApp ( t * testing . T ) * fiber . App {
t . Helper ( )
@ -280,7 +280,7 @@ func setupApp(t *testing.T) *fiber.App {
return app
}
// TestSessionFlowEndpoints validates start, session read, question read, answer, hint, and end flows .
// TestSessionFlowEndpoints ensures session flow endpoints behavior is handled correctly .
func TestSessionFlowEndpoints ( t * testing . T ) {
app := setupApp ( t )
@ -328,7 +328,7 @@ func TestSessionFlowEndpoints(t *testing.T) {
}
}
// TestSessionUnauthorizedAndForbidden validates auth and ownership guards on session endpoints .
// TestSessionUnauthorizedAndForbidden ensures session unauthorized and forbidden behavior is handled correctly .
func TestSessionUnauthorizedAndForbidden ( t * testing . T ) {
app := setupApp ( t )
@ -363,7 +363,7 @@ func TestSessionUnauthorizedAndForbidden(t *testing.T) {
}
}
// TestMetricsEndpoint verifies /metrics is reachable .
// TestMetricsEndpoint ensures metrics endpoint behavior is handled correctly .
func TestMetricsEndpoint ( t * testing . T ) {
app := setupApp ( t )
req := httptest . NewRequest ( http . MethodGet , "/metrics" , nil )
@ -372,7 +372,7 @@ func TestMetricsEndpoint(t *testing.T) {
assertStatus ( t , resp , http . StatusOK , "metrics failed" )
}
// mustJSONRequest is a test helper .
// mustJSONRequest builds request fixtures and fails fast on malformed setup .
func mustJSONRequest (
t * testing . T ,
app * fiber . App ,
@ -399,7 +399,7 @@ func mustJSONRequest(
return sharedhttpx . MustTest ( t , app , req )
}
// assertStatus is a test helper .
// assertStatus asserts HTTP status codes and response payload invariants .
func assertStatus ( t * testing . T , resp * http . Response , want int , msg string ) {
t . Helper ( )
if resp . StatusCode != want {
@ -407,7 +407,7 @@ func assertStatus(t *testing.T, resp *http.Response, want int, msg string) {
}
}
// decodeDataMap is a test helper .
// decodeDataMap decodes response data into assertion-friendly structures .
func decodeDataMap ( t * testing . T , resp * http . Response ) map [ string ] any {
t . Helper ( )
@ -421,7 +421,7 @@ func decodeDataMap(t *testing.T, resp *http.Response) map[string]any {
return payload . Data
}
// asMap is a test helper .
// asMap decodes response data into assertion-friendly structures .
func asMap ( t * testing . T , v any ) map [ string ] any {
t . Helper ( )
m , ok := v . ( map [ string ] any )
@ -431,7 +431,7 @@ func asMap(t *testing.T, v any) map[string]any {
return m
}
// asString is a test helper .
// asString decodes response data into assertion-friendly structures .
func asString ( t * testing . T , v any ) string {
t . Helper ( )
s , ok := v . ( string )
@ -441,7 +441,7 @@ func asString(t *testing.T, v any) string {
return s
}
// decodeAny is a test helper .
// decodeAny decodes response data into assertion-friendly structures .
func decodeAny ( t * testing . T , resp * http . Response ) map [ string ] any {
t . Helper ( )
