@rooguys/js 0.1.0 → 1.0.0

package/src/__tests__/property/leaderboard-filter.property.test.js

@@ -0,0 +1,585 @@
+/**
+ * Property-Based Test: Leaderboard Filter Query Construction
+ * Feature: sdk-documentation-update, Property 10: Leaderboard Filter Query Construction
+ * Validates: Requirements 6.1, 6.2, 6.3
+ * 
+ * For any leaderboard request with filter parameters (persona, minLevel, maxLevel, 
+ * startDate, endDate), the SDK SHALL include the corresponding query parameters 
+ * with correctly formatted values (dates as ISO 8601).
+ */
+
+import fc from 'fast-check';
+import { jest } from '@jest/globals';
+import Rooguys from '../../index.js';
+import { createMockFetch, createMockHeaders } from '../utils/mockClient.js';
+
+describe('Property 10: Leaderboard Filter Query Construction', () => {
+  let mockFetch;
+
+  beforeEach(() => {
+    mockFetch = createMockFetch();
+    global.fetch = mockFetch;
+  });
+
+  afterEach(() => {
+    jest.clearAllMocks();
+  });
+
+  const createSuccessResponse = (data) => ({
+    ok: true,
+    headers: createMockHeaders({
+      'X-RateLimit-Limit': '1000',
+      'X-RateLimit-Remaining': '950',
+      'X-RateLimit-Reset': '1704067200',
+    }),
+    json: async () => ({
+      success: true,
+      data,
+    }),
+  });
+
+  const leaderboardResponse = {
+    rankings: [],
+    pagination: { page: 1, limit: 50, total: 0, totalPages: 0 },
+  };
+
+  // Generator for valid persona names
+  const validPersona = fc.constantFrom(
+    'Achiever',
+    'Explorer',
+    'Competitor',
+    'Socializer'
+  );
+
+  // Generator for level numbers
+  const levelNumber = fc.integer({ min: 1, max: 100 });
+
+  // Generator for valid dates within a reasonable range
+  const validDate = fc.date({
+    min: new Date('2020-01-01'),
+    max: new Date('2030-12-31'),
+  });
+
+  // Generator for timeframe
+  const timeframe = fc.constantFrom('all-time', 'weekly', 'monthly');
+
+  // Generator for pagination
+  const pagination = fc.record({
+    page: fc.integer({ min: 1, max: 100 }),
+    limit: fc.integer({ min: 1, max: 100 }),
+  });
+
+  describe('Persona Filter (Requirement 6.1)', () => {
+    it('should include persona query parameter when provided', async () => {
+      await fc.assert(
+        fc.asyncProperty(
+          fc.string({ minLength: 10, maxLength: 100 }), // API key
+          validPersona,
+          async (apiKey, persona) => {
+            // Arrange
+            mockFetch.mockClear();
+            mockFetch.mockResolvedValue(createSuccessResponse(leaderboardResponse));
+            const sdk = new Rooguys(apiKey);
+
+            // Act
+            await sdk.leaderboards.getGlobal({ persona });
+
+            // Assert
+            expect(mockFetch).toHaveBeenCalledTimes(1);
+            const callUrl = mockFetch.mock.calls[0][0];
+            const url = new URL(callUrl);
+            
+            expect(url.searchParams.get('persona')).toBe(persona);
+          }
+        ),
+        { numRuns: 100 }
+      );
+    });
+
+    it('should not include persona parameter when not provided', async () => {
+      await fc.assert(
+        fc.asyncProperty(
+          fc.string({ minLength: 10, maxLength: 100 }), // API key
+          async (apiKey) => {
+            // Arrange
+            mockFetch.mockClear();
+            mockFetch.mockResolvedValue(createSuccessResponse(leaderboardResponse));
+            const sdk = new Rooguys(apiKey);
+
+            // Act
+            await sdk.leaderboards.getGlobal({});
+
+            // Assert
+            const callUrl = mockFetch.mock.calls[0][0];
+            const url = new URL(callUrl);
+            
+            expect(url.searchParams.has('persona')).toBe(false);
+          }
+        ),
+        { numRuns: 100 }
+      );
+    });
+
+    it('should include persona filter in custom leaderboard requests', async () => {
+      await fc.assert(
+        fc.asyncProperty(
+          fc.string({ minLength: 10, maxLength: 100 }), // API key
+          fc.uuid(), // Leaderboard ID
+          validPersona,
+          async (apiKey, leaderboardId, persona) => {
+            // Arrange
+            mockFetch.mockClear();
+            mockFetch.mockResolvedValue(createSuccessResponse(leaderboardResponse));
+            const sdk = new Rooguys(apiKey);
+
+            // Act
+            await sdk.leaderboards.getCustom(leaderboardId, { persona });
+
+            // Assert
+            const callUrl = mockFetch.mock.calls[0][0];
+            const url = new URL(callUrl);
+            
+            expect(url.searchParams.get('persona')).toBe(persona);
+          }
+        ),
+        { numRuns: 100 }
+      );
+    });
+  });
+
+  describe('Level Range Filter (Requirement 6.2)', () => {
+    it('should include minLevel query parameter when provided', async () => {
+      await fc.assert(
+        fc.asyncProperty(
+          fc.string({ minLength: 10, maxLength: 100 }), // API key
+          levelNumber,
+          async (apiKey, minLevel) => {
+            // Arrange
+            mockFetch.mockClear();
+            mockFetch.mockResolvedValue(createSuccessResponse(leaderboardResponse));
+            const sdk = new Rooguys(apiKey);
+
+            // Act
+            await sdk.leaderboards.getGlobal({ minLevel });
+
+            // Assert
+            const callUrl = mockFetch.mock.calls[0][0];
+            const url = new URL(callUrl);
+            
+            expect(url.searchParams.get('min_level')).toBe(String(minLevel));
+          }
+        ),
+        { numRuns: 100 }
+      );
+    });
+
+    it('should include maxLevel query parameter when provided', async () => {
+      await fc.assert(
+        fc.asyncProperty(
+          fc.string({ minLength: 10, maxLength: 100 }), // API key
+          levelNumber,
+          async (apiKey, maxLevel) => {
+            // Arrange
+            mockFetch.mockClear();
+            mockFetch.mockResolvedValue(createSuccessResponse(leaderboardResponse));
+            const sdk = new Rooguys(apiKey);
+
+            // Act
+            await sdk.leaderboards.getGlobal({ maxLevel });
+
+            // Assert
+            const callUrl = mockFetch.mock.calls[0][0];
+            const url = new URL(callUrl);
+            
+            expect(url.searchParams.get('max_level')).toBe(String(maxLevel));
+          }
+        ),
+        { numRuns: 100 }
+      );
+    });
+
+    it('should include both minLevel and maxLevel when provided', async () => {
+      await fc.assert(
+        fc.asyncProperty(
+          fc.string({ minLength: 10, maxLength: 100 }), // API key
+          levelNumber,
+          levelNumber,
+          async (apiKey, minLevel, maxLevel) => {
+            // Arrange
+            mockFetch.mockClear();
+            mockFetch.mockResolvedValue(createSuccessResponse(leaderboardResponse));
+            const sdk = new Rooguys(apiKey);
+
+            // Act
+            await sdk.leaderboards.getGlobal({ minLevel, maxLevel });
+
+            // Assert
+            const callUrl = mockFetch.mock.calls[0][0];
+            const url = new URL(callUrl);
+            
+            expect(url.searchParams.get('min_level')).toBe(String(minLevel));
+            expect(url.searchParams.get('max_level')).toBe(String(maxLevel));
+          }
+        ),
+        { numRuns: 100 }
+      );
+    });
+
+    it('should not include level parameters when not provided', async () => {
+      await fc.assert(
+        fc.asyncProperty(
+          fc.string({ minLength: 10, maxLength: 100 }), // API key
+          async (apiKey) => {
+            // Arrange
+            mockFetch.mockClear();
+            mockFetch.mockResolvedValue(createSuccessResponse(leaderboardResponse));
+            const sdk = new Rooguys(apiKey);
+
+            // Act
+            await sdk.leaderboards.getGlobal({});
+
+            // Assert
+            const callUrl = mockFetch.mock.calls[0][0];
+            const url = new URL(callUrl);
+            
+            expect(url.searchParams.has('min_level')).toBe(false);
+            expect(url.searchParams.has('max_level')).toBe(false);
+          }
+        ),
+        { numRuns: 100 }
+      );
+    });
+  });
+
+  describe('Date Range Filter (Requirement 6.3)', () => {
+    it('should format startDate as ISO 8601 string', async () => {
+      await fc.assert(
+        fc.asyncProperty(
+          fc.string({ minLength: 10, maxLength: 100 }), // API key
+          validDate,
+          async (apiKey, startDate) => {
+            // Arrange
+            mockFetch.mockClear();
+            mockFetch.mockResolvedValue(createSuccessResponse(leaderboardResponse));
+            const sdk = new Rooguys(apiKey);
+
+            // Act
+            await sdk.leaderboards.getGlobal({ startDate });
+
+            // Assert
+            const callUrl = mockFetch.mock.calls[0][0];
+            const url = new URL(callUrl);
+            const startDateParam = url.searchParams.get('start_date');
+            
+            expect(startDateParam).toBe(startDate.toISOString());
+            
+            // Verify it's a valid ISO 8601 date
+            const parsedDate = new Date(startDateParam);
+            expect(parsedDate.getTime()).toBe(startDate.getTime());
+          }
+        ),
+        { numRuns: 100 }
+      );
+    });
+
+    it('should format endDate as ISO 8601 string', async () => {
+      await fc.assert(
+        fc.asyncProperty(
+          fc.string({ minLength: 10, maxLength: 100 }), // API key
+          validDate,
+          async (apiKey, endDate) => {
+            // Arrange
+            mockFetch.mockClear();
+            mockFetch.mockResolvedValue(createSuccessResponse(leaderboardResponse));
+            const sdk = new Rooguys(apiKey);
+
+            // Act
+            await sdk.leaderboards.getGlobal({ endDate });
+
+            // Assert
+            const callUrl = mockFetch.mock.calls[0][0];
+            const url = new URL(callUrl);
+            const endDateParam = url.searchParams.get('end_date');
+            
+            expect(endDateParam).toBe(endDate.toISOString());
+            
+            // Verify it's a valid ISO 8601 date
+            const parsedDate = new Date(endDateParam);
+            expect(parsedDate.getTime()).toBe(endDate.getTime());
+          }
+        ),
+        { numRuns: 100 }
+      );
+    });
+
+    it('should include both startDate and endDate when provided', async () => {
+      await fc.assert(
+        fc.asyncProperty(
+          fc.string({ minLength: 10, maxLength: 100 }), // API key
+          validDate,
+          validDate,
+          async (apiKey, startDate, endDate) => {
+            // Arrange
+            mockFetch.mockClear();
+            mockFetch.mockResolvedValue(createSuccessResponse(leaderboardResponse));
+            const sdk = new Rooguys(apiKey);
+
+            // Act
+            await sdk.leaderboards.getGlobal({ startDate, endDate });
+
+            // Assert
+            const callUrl = mockFetch.mock.calls[0][0];
+            const url = new URL(callUrl);
+            
+            expect(url.searchParams.get('start_date')).toBe(startDate.toISOString());
+            expect(url.searchParams.get('end_date')).toBe(endDate.toISOString());
+          }
+        ),
+        { numRuns: 100 }
+      );
+    });
+
+    it('should accept ISO string dates and convert them correctly', async () => {
+      await fc.assert(
+        fc.asyncProperty(
+          fc.string({ minLength: 10, maxLength: 100 }), // API key
+          validDate,
+          async (apiKey, date) => {
+            // Arrange
+            mockFetch.mockClear();
+            mockFetch.mockResolvedValue(createSuccessResponse(leaderboardResponse));
+            const sdk = new Rooguys(apiKey);
+            const isoString = date.toISOString();
+
+            // Act
+            await sdk.leaderboards.getGlobal({ startDate: isoString });
+
+            // Assert
+            const callUrl = mockFetch.mock.calls[0][0];
+            const url = new URL(callUrl);
+            const startDateParam = url.searchParams.get('start_date');
+            
+            // Should be a valid ISO 8601 date
+            const parsedDate = new Date(startDateParam);
+            expect(parsedDate.getTime()).toBe(date.getTime());
+          }
+        ),
+        { numRuns: 100 }
+      );
+    });
+
+    it('should not include date parameters when not provided', async () => {
+      await fc.assert(
+        fc.asyncProperty(
+          fc.string({ minLength: 10, maxLength: 100 }), // API key
+          async (apiKey) => {
+            // Arrange
+            mockFetch.mockClear();
+            mockFetch.mockResolvedValue(createSuccessResponse(leaderboardResponse));
+            const sdk = new Rooguys(apiKey);
+
+            // Act
+            await sdk.leaderboards.getGlobal({});
+
+            // Assert
+            const callUrl = mockFetch.mock.calls[0][0];
+            const url = new URL(callUrl);
+            
+            expect(url.searchParams.has('start_date')).toBe(false);
+            expect(url.searchParams.has('end_date')).toBe(false);
+          }
+        ),
+        { numRuns: 100 }
+      );
+    });
+  });
+
+  describe('Combined Filters', () => {
+    it('should include all filter parameters when all are provided', async () => {
+      await fc.assert(
+        fc.asyncProperty(
+          fc.string({ minLength: 10, maxLength: 100 }), // API key
+          validPersona,
+          levelNumber,
+          levelNumber,
+          validDate,
+          validDate,
+          timeframe,
+          pagination,
+          async (apiKey, persona, minLevel, maxLevel, startDate, endDate, tf, pag) => {
+            // Arrange
+            mockFetch.mockClear();
+            mockFetch.mockResolvedValue(createSuccessResponse(leaderboardResponse));
+            const sdk = new Rooguys(apiKey);
+
+            // Act
+            await sdk.leaderboards.getGlobal({
+              timeframe: tf,
+              page: pag.page,
+              limit: pag.limit,
+              persona,
+              minLevel,
+              maxLevel,
+              startDate,
+              endDate,
+            });
+
+            // Assert
+            const callUrl = mockFetch.mock.calls[0][0];
+            const url = new URL(callUrl);
+            
+            // Verify all parameters are present
+            expect(url.searchParams.get('timeframe')).toBe(tf);
+            expect(url.searchParams.get('page')).toBe(String(pag.page));
+            expect(url.searchParams.get('limit')).toBe(String(pag.limit));
+            expect(url.searchParams.get('persona')).toBe(persona);
+            expect(url.searchParams.get('min_level')).toBe(String(minLevel));
+            expect(url.searchParams.get('max_level')).toBe(String(maxLevel));
+            expect(url.searchParams.get('start_date')).toBe(startDate.toISOString());
+            expect(url.searchParams.get('end_date')).toBe(endDate.toISOString());
+          }
+        ),
+        { numRuns: 100 }
+      );
+    });
+
+    it('should work with custom leaderboard and all filters', async () => {
+      await fc.assert(
+        fc.asyncProperty(
+          fc.string({ minLength: 10, maxLength: 100 }), // API key
+          fc.uuid(), // Leaderboard ID
+          validPersona,
+          levelNumber,
+          levelNumber,
+          validDate,
+          validDate,
+          async (apiKey, leaderboardId, persona, minLevel, maxLevel, startDate, endDate) => {
+            // Arrange
+            mockFetch.mockClear();
+            mockFetch.mockResolvedValue(createSuccessResponse(leaderboardResponse));
+            const sdk = new Rooguys(apiKey);
+
+            // Act
+            await sdk.leaderboards.getCustom(leaderboardId, {
+              persona,
+              minLevel,
+              maxLevel,
+              startDate,
+              endDate,
+            });
+
+            // Assert
+            const callUrl = mockFetch.mock.calls[0][0];
+            const url = new URL(callUrl);
+            
+            // Verify endpoint contains leaderboard ID
+            expect(url.pathname).toContain(leaderboardId);
+            
+            // Verify all filter parameters are present
+            expect(url.searchParams.get('persona')).toBe(persona);
+            expect(url.searchParams.get('min_level')).toBe(String(minLevel));
+            expect(url.searchParams.get('max_level')).toBe(String(maxLevel));
+            expect(url.searchParams.get('start_date')).toBe(startDate.toISOString());
+            expect(url.searchParams.get('end_date')).toBe(endDate.toISOString());
+          }
+        ),
+        { numRuns: 100 }
+      );
+    });
+
+    it('should only include provided filters (partial filter set)', async () => {
+      await fc.assert(
+        fc.asyncProperty(
+          fc.string({ minLength: 10, maxLength: 100 }), // API key
+          fc.option(validPersona, { nil: undefined }),
+          fc.option(levelNumber, { nil: undefined }),
+          fc.option(levelNumber, { nil: undefined }),
+          fc.option(validDate, { nil: undefined }),
+          fc.option(validDate, { nil: undefined }),
+          async (apiKey, persona, minLevel, maxLevel, startDate, endDate) => {
+            // Arrange
+            mockFetch.mockClear();
+            mockFetch.mockResolvedValue(createSuccessResponse(leaderboardResponse));
+            const sdk = new Rooguys(apiKey);
+
+            const options = {};
+            if (persona !== undefined) options.persona = persona;
+            if (minLevel !== undefined) options.minLevel = minLevel;
+            if (maxLevel !== undefined) options.maxLevel = maxLevel;
+            if (startDate !== undefined) options.startDate = startDate;
+            if (endDate !== undefined) options.endDate = endDate;
+
+            // Act
+            await sdk.leaderboards.getGlobal(options);
+
+            // Assert
+            const callUrl = mockFetch.mock.calls[0][0];
+            const url = new URL(callUrl);
+            
+            // Verify only provided parameters are present
+            expect(url.searchParams.has('persona')).toBe(persona !== undefined);
+            expect(url.searchParams.has('min_level')).toBe(minLevel !== undefined);
+            expect(url.searchParams.has('max_level')).toBe(maxLevel !== undefined);
+            expect(url.searchParams.has('start_date')).toBe(startDate !== undefined);
+            expect(url.searchParams.has('end_date')).toBe(endDate !== undefined);
+            
+            // Verify values are correct for provided parameters
+            if (persona !== undefined) {
+              expect(url.searchParams.get('persona')).toBe(persona);
+            }
+            if (minLevel !== undefined) {
+              expect(url.searchParams.get('min_level')).toBe(String(minLevel));
+            }
+            if (maxLevel !== undefined) {
+              expect(url.searchParams.get('max_level')).toBe(String(maxLevel));
+            }
+            if (startDate !== undefined) {
+              expect(url.searchParams.get('start_date')).toBe(startDate.toISOString());
+            }
+            if (endDate !== undefined) {
+              expect(url.searchParams.get('end_date')).toBe(endDate.toISOString());
+            }
+          }
+        ),
+        { numRuns: 100 }
+      );
+    });
+  });
+
+  describe('Null value handling', () => {
+    it('should not include parameters with null values', async () => {
+      await fc.assert(
+        fc.asyncProperty(
+          fc.string({ minLength: 10, maxLength: 100 }), // API key
+          async (apiKey) => {
+            // Arrange
+            mockFetch.mockClear();
+            mockFetch.mockResolvedValue(createSuccessResponse(leaderboardResponse));
+            const sdk = new Rooguys(apiKey);
+
+            // Act
+            await sdk.leaderboards.getGlobal({
+              persona: null,
+              minLevel: null,
+              maxLevel: null,
+              startDate: null,
+              endDate: null,
+            });
+
+            // Assert
+            const callUrl = mockFetch.mock.calls[0][0];
+            const url = new URL(callUrl);
+            
+            // Verify null parameters are NOT included
+            expect(url.searchParams.has('persona')).toBe(false);
+            expect(url.searchParams.has('min_level')).toBe(false);
+            expect(url.searchParams.has('max_level')).toBe(false);
+            expect(url.searchParams.has('start_date')).toBe(false);
+            expect(url.searchParams.has('end_date')).toBe(false);
+          }
+        ),
+        { numRuns: 100 }
+      );
+    });
+  });
+});