@rooguys/js 0.1.0 → 1.0.0

package/src/__tests__/property/email-validation.property.test.js

@@ -0,0 +1,272 @@
+/**
+ * Property-Based Test: Email Validation
+ * Feature: sdk-documentation-update, Property 7: Email Validation
+ * Validates: Requirements 4.5
+ * 
+ * For any user creation or update with an email field, the SDK SHALL validate
+ * the email format client-side. Invalid emails SHALL cause a ValidationError
+ * to be thrown before making an API request.
+ */
+
+import fc from 'fast-check';
+import { jest } from '@jest/globals';
+import Rooguys, { ValidationError } from '../../index.js';
+import { createMockFetch, createMockHeaders } from '../utils/mockClient.js';
+
+describe('Property 7: Email Validation', () => {
+  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,
+    }),
+  });
+
+  // Generator for valid emails
+  const validEmail = fc.tuple(
+    fc.string({ minLength: 1, maxLength: 50 }).filter(s => /^[a-zA-Z0-9._+-]+$/.test(s) && s.length > 0),
+    fc.string({ minLength: 1, maxLength: 30 }).filter(s => /^[a-zA-Z0-9.-]+$/.test(s) && s.length > 0),
+    fc.constantFrom('com', 'org', 'net', 'io', 'co.uk', 'edu', 'gov')
+  ).map(([local, domain, tld]) => `${local}@${domain}.${tld}`);
+
+  // Generator for invalid emails (missing @, missing domain, etc.)
+  const invalidEmail = fc.oneof(
+    // Missing @ symbol
+    fc.string({ minLength: 1, maxLength: 50 }).filter(s => !s.includes('@') && s.trim().length > 0),
+    // Missing local part
+    fc.string({ minLength: 1, maxLength: 30 }).map(s => `@${s}.com`),
+    // Missing domain
+    fc.string({ minLength: 1, maxLength: 30 }).map(s => `${s}@`),
+    // Missing TLD
+    fc.string({ minLength: 1, maxLength: 30 }).map(s => `${s}@domain`),
+    // Multiple @ symbols
+    fc.tuple(
+      fc.string({ minLength: 1, maxLength: 20 }),
+      fc.string({ minLength: 1, maxLength: 20 }),
+      fc.string({ minLength: 1, maxLength: 20 })
+    ).map(([a, b, c]) => `${a}@${b}@${c}.com`),
+    // Whitespace only
+    fc.constantFrom('   ', '\t', '\n'),
+    // Just dots
+    fc.constantFrom('.', '..', '...'),
+  );
+
+  describe('users.create()', () => {
+    it('should accept valid email formats without throwing ValidationError', async () => {
+      await fc.assert(
+        fc.asyncProperty(
+          fc.string({ minLength: 10, maxLength: 100 }), // API key
+          fc.string({ minLength: 1, maxLength: 50 }).filter(s => s.trim().length > 0), // User ID
+          validEmail,
+          async (apiKey, userId, email) => {
+            // Arrange
+            mockFetch.mockClear();
+            mockFetch.mockResolvedValue(createSuccessResponse({
+              user_id: userId,
+              email,
+              points: 0,
+            }));
+            const sdk = new Rooguys(apiKey);
+
+            // Act - should not throw
+            const result = await sdk.users.create({ userId, email });
+
+            // Assert - API request was made
+            expect(mockFetch).toHaveBeenCalledTimes(1);
+            expect(result.user_id).toBe(userId);
+          }
+        ),
+        { numRuns: 100 }
+      );
+    });
+
+    it('should throw ValidationError for invalid email formats before making API request', async () => {
+      await fc.assert(
+        fc.asyncProperty(
+          fc.string({ minLength: 10, maxLength: 100 }), // API key
+          fc.string({ minLength: 1, maxLength: 50 }).filter(s => s.trim().length > 0), // User ID
+          invalidEmail,
+          async (apiKey, userId, email) => {
+            // Arrange
+            mockFetch.mockClear();
+            const sdk = new Rooguys(apiKey);
+
+            // Act & Assert
+            await expect(sdk.users.create({ userId, email })).rejects.toThrow(ValidationError);
+            await expect(sdk.users.create({ userId, email })).rejects.toThrow('Invalid email format');
+
+            // Verify no API request was made
+            expect(mockFetch).not.toHaveBeenCalled();
+          }
+        ),
+        { numRuns: 100 }
+      );
+    });
+
+    it('should allow user creation without email (optional field)', async () => {
+      await fc.assert(
+        fc.asyncProperty(
+          fc.string({ minLength: 10, maxLength: 100 }), // API key
+          fc.string({ minLength: 1, maxLength: 50 }).filter(s => s.trim().length > 0), // User ID
+          async (apiKey, userId) => {
+            // Arrange
+            mockFetch.mockClear();
+            mockFetch.mockResolvedValue(createSuccessResponse({
+              user_id: userId,
+              points: 0,
+            }));
+            const sdk = new Rooguys(apiKey);
+
+            // Act - should not throw
+            const result = await sdk.users.create({ userId });
+
+            // Assert - API request was made
+            expect(mockFetch).toHaveBeenCalledTimes(1);
+            expect(result.user_id).toBe(userId);
+          }
+        ),
+        { numRuns: 100 }
+      );
+    });
+  });
+
+  describe('users.update()', () => {
+    it('should accept valid email formats in updates without throwing ValidationError', async () => {
+      await fc.assert(
+        fc.asyncProperty(
+          fc.string({ minLength: 10, maxLength: 100 }), // API key
+          fc.string({ minLength: 1, maxLength: 50 }).filter(s => s.trim().length > 0), // User ID
+          validEmail,
+          async (apiKey, userId, email) => {
+            // Arrange
+            mockFetch.mockClear();
+            mockFetch.mockResolvedValue(createSuccessResponse({
+              user_id: userId,
+              email,
+              points: 100,
+            }));
+            const sdk = new Rooguys(apiKey);
+
+            // Act - should not throw
+            const result = await sdk.users.update(userId, { email });
+
+            // Assert - API request was made
+            expect(mockFetch).toHaveBeenCalledTimes(1);
+            expect(result.email).toBe(email);
+          }
+        ),
+        { numRuns: 100 }
+      );
+    });
+
+    it('should throw ValidationError for invalid email formats in updates before making API request', async () => {
+      await fc.assert(
+        fc.asyncProperty(
+          fc.string({ minLength: 10, maxLength: 100 }), // API key
+          fc.string({ minLength: 1, maxLength: 50 }).filter(s => s.trim().length > 0), // User ID
+          invalidEmail,
+          async (apiKey, userId, email) => {
+            // Arrange
+            mockFetch.mockClear();
+            const sdk = new Rooguys(apiKey);
+
+            // Act & Assert
+            await expect(sdk.users.update(userId, { email })).rejects.toThrow(ValidationError);
+            await expect(sdk.users.update(userId, { email })).rejects.toThrow('Invalid email format');
+
+            // Verify no API request was made
+            expect(mockFetch).not.toHaveBeenCalled();
+          }
+        ),
+        { numRuns: 100 }
+      );
+    });
+  });
+
+  describe('users.createBatch()', () => {
+    it('should accept valid email formats in batch without throwing ValidationError', async () => {
+      await fc.assert(
+        fc.asyncProperty(
+          fc.string({ minLength: 10, maxLength: 100 }), // API key
+          fc.array(
+            fc.record({
+              userId: fc.string({ minLength: 1, maxLength: 50 }).filter(s => s.trim().length > 0),
+              email: validEmail,
+            }),
+            { minLength: 1, maxLength: 10 }
+          ),
+          async (apiKey, users) => {
+            // Arrange
+            mockFetch.mockClear();
+            mockFetch.mockResolvedValue(createSuccessResponse({
+              results: users.map((_, i) => ({ index: i, status: 'created' })),
+            }));
+            const sdk = new Rooguys(apiKey);
+
+            // Act - should not throw
+            const result = await sdk.users.createBatch(users);
+
+            // Assert - API request was made
+            expect(mockFetch).toHaveBeenCalledTimes(1);
+            expect(result.results).toHaveLength(users.length);
+          }
+        ),
+        { numRuns: 100 }
+      );
+    });
+
+    it('should throw ValidationError for any invalid email in batch before making API request', async () => {
+      await fc.assert(
+        fc.asyncProperty(
+          fc.string({ minLength: 10, maxLength: 100 }), // API key
+          fc.integer({ min: 0, max: 5 }), // Index of invalid email
+          fc.array(
+            fc.record({
+              userId: fc.string({ minLength: 1, maxLength: 50 }).filter(s => s.trim().length > 0),
+              email: validEmail,
+            }),
+            { minLength: 1, maxLength: 5 }
+          ),
+          invalidEmail,
+          async (apiKey, invalidIndex, validUsers, invalidEmailValue) => {
+            // Arrange
+            mockFetch.mockClear();
+            const sdk = new Rooguys(apiKey);
+            
+            // Insert invalid email at specified index
+            const users = [...validUsers];
+            const actualIndex = Math.min(invalidIndex, users.length);
+            users.splice(actualIndex, 0, {
+              userId: `invalid_user_${actualIndex}`,
+              email: invalidEmailValue,
+            });
+
+            // Act & Assert
+            await expect(sdk.users.createBatch(users)).rejects.toThrow(ValidationError);
+            await expect(sdk.users.createBatch(users)).rejects.toThrow('Invalid email format');
+
+            // Verify no API request was made
+            expect(mockFetch).not.toHaveBeenCalled();
+          }
+        ),
+        { numRuns: 100 }
+      );
+    });
+  });
+});