digiqagent 1.2.0

package/skills/postman-test-suite-generator/test-scenario-patterns.md

@@ -0,0 +1,612 @@
+# Test Scenario Patterns
+
+Reference patterns for Postman test scripts. Copy and adapt for generated test suites.
+
+## Complete CRUD Test Suite Example — `/api/users`
+
+A full working test suite for a Users resource showing both positive and negative scenarios.
+
+### Setup — Login
+
+```javascript
+// Test script for POST /api/auth/login
+pm.test("Login successful", function () {
+    pm.response.to.have.status(200);
+});
+
+pm.test("Response contains token", function () {
+    const response = pm.response.json();
+    pm.expect(response).to.have.property("accessToken");
+    pm.environment.set("authToken", response.accessToken);
+    if (response.user) {
+        pm.environment.set("currentUserId", response.user.id);
+    }
+});
+```
+
+### Positive — Create User
+
+```javascript
+// Test script for POST /api/users
+// Body: { "name": "Jane Smith", "email": "jane.smith@example.com", "password": "SecureP@ss123", "role": "user" }
+
+pm.test("Status code is 201", function () {
+    pm.response.to.have.status(201);
+});
+
+pm.test("Response time is acceptable", function () {
+    pm.expect(pm.response.responseTime).to.be.below(2000);
+});
+
+pm.test("Response has user object with all expected fields", function () {
+    const user = pm.response.json();
+    pm.expect(user).to.have.property("id");
+    pm.expect(user).to.have.property("name");
+    pm.expect(user).to.have.property("email");
+    pm.expect(user).to.have.property("role");
+    pm.expect(user).to.have.property("createdAt");
+});
+
+pm.test("Response data matches request", function () {
+    const request = JSON.parse(pm.request.body.raw);
+    const user = pm.response.json();
+    pm.expect(user.name).to.eql(request.name);
+    pm.expect(user.email).to.eql(request.email);
+    pm.expect(user.role).to.eql(request.role);
+});
+
+pm.test("Password is not returned in response", function () {
+    const user = pm.response.json();
+    pm.expect(user).to.not.have.property("password");
+    pm.expect(user).to.not.have.property("passwordHash");
+});
+
+pm.test("ID is a valid format", function () {
+    const user = pm.response.json();
+    pm.expect(user.id).to.be.a("string");
+    pm.expect(user.id).to.not.be.empty;
+});
+
+// Capture for subsequent tests
+if (pm.response.code === 201) {
+    pm.environment.set("testUserId", pm.response.json().id);
+    pm.environment.set("testUserEmail", pm.response.json().email);
+}
+```
+
+### Positive — List Users
+
+```javascript
+// Test script for GET /api/users?page=1&limit=10
+
+pm.test("Status code is 200", function () {
+    pm.response.to.have.status(200);
+});
+
+pm.test("Response is paginated array", function () {
+    const response = pm.response.json();
+    pm.expect(response).to.have.property("data");
+    pm.expect(response.data).to.be.an("array");
+    pm.expect(response).to.have.property("meta");
+});
+
+pm.test("Pagination metadata is correct", function () {
+    const meta = pm.response.json().meta;
+    pm.expect(meta.page).to.be.a("number");
+    pm.expect(meta.limit).to.be.a("number");
+    pm.expect(meta.totalItems).to.be.a("number");
+    pm.expect(meta.totalPages).to.be.a("number");
+    pm.expect(meta.page).to.eql(1);
+    pm.expect(meta.limit).to.eql(10);
+});
+
+pm.test("Each user has expected fields", function () {
+    const users = pm.response.json().data;
+    if (users.length > 0) {
+        users.forEach(function (user) {
+            pm.expect(user).to.have.property("id");
+            pm.expect(user).to.have.property("name");
+            pm.expect(user).to.have.property("email");
+        });
+    }
+});
+
+pm.test("Previously created user is in the list", function () {
+    const users = pm.response.json().data;
+    const testUserId = pm.environment.get("testUserId");
+    if (testUserId) {
+        const found = users.some(u => u.id === testUserId);
+        pm.expect(found).to.be.true;
+    }
+});
+```
+
+### Positive — Get User by ID
+
+```javascript
+// Test script for GET /api/users/{{testUserId}}
+
+pm.test("Status code is 200", function () {
+    pm.response.to.have.status(200);
+});
+
+pm.test("Returns the correct user", function () {
+    const user = pm.response.json();
+    pm.expect(user.id).to.eql(pm.environment.get("testUserId"));
+    pm.expect(user.email).to.eql(pm.environment.get("testUserEmail"));
+});
+
+pm.test("User has all expected fields", function () {
+    const user = pm.response.json();
+    pm.expect(user).to.have.all.keys("id", "name", "email", "role", "createdAt", "updatedAt");
+});
+```
+
+### Positive — Update User
+
+```javascript
+// Test script for PUT /api/users/{{testUserId}}
+// Body: { "name": "Jane Smith Updated" }
+
+pm.test("Status code is 200", function () {
+    pm.response.to.have.status(200);
+});
+
+pm.test("Name is updated", function () {
+    const user = pm.response.json();
+    pm.expect(user.name).to.eql("Jane Smith Updated");
+});
+
+pm.test("Other fields unchanged", function () {
+    const user = pm.response.json();
+    pm.expect(user.email).to.eql(pm.environment.get("testUserEmail"));
+    pm.expect(user.id).to.eql(pm.environment.get("testUserId"));
+});
+
+pm.test("updatedAt is after createdAt", function () {
+    const user = pm.response.json();
+    if (user.updatedAt && user.createdAt) {
+        pm.expect(new Date(user.updatedAt).getTime()).to.be.at.least(new Date(user.createdAt).getTime());
+    }
+});
+```
+
+### Positive — Delete User
+
+```javascript
+// Test script for DELETE /api/users/{{testUserId}}
+
+pm.test("Status code is 200 or 204", function () {
+    pm.expect(pm.response.code).to.be.oneOf([200, 204]);
+});
+```
+
+### Positive — Verify Deletion
+
+```javascript
+// Test script for GET /api/users/{{testUserId}} after deletion
+
+pm.test("Returns 404 after deletion", function () {
+    pm.response.to.have.status(404);
+});
+```
+
+### Negative — Missing Required Fields
+
+```javascript
+// POST /api/users — missing "name"
+// Body: { "email": "test@example.com", "password": "SecureP@ss123" }
+
+pm.test("Returns 400 for missing name", function () {
+    pm.response.to.have.status(400);
+});
+
+pm.test("Error response has expected structure", function () {
+    const error = pm.response.json();
+    pm.expect(error).to.have.property("message");
+    pm.expect(error).to.have.property("error");
+});
+
+pm.test("Error message references the missing field", function () {
+    const error = pm.response.json();
+    const msg = Array.isArray(error.message) ? error.message.join(" ") : error.message;
+    pm.expect(msg.toLowerCase()).to.include("name");
+});
+```
+
+```javascript
+// POST /api/users — missing "email"
+// Body: { "name": "Jane Smith", "password": "SecureP@ss123" }
+
+pm.test("Returns 400 for missing email", function () {
+    pm.response.to.have.status(400);
+});
+
+pm.test("Error message references email", function () {
+    const error = pm.response.json();
+    const msg = Array.isArray(error.message) ? error.message.join(" ") : error.message;
+    pm.expect(msg.toLowerCase()).to.include("email");
+});
+```
+
+```javascript
+// POST /api/users — missing "password"
+// Body: { "name": "Jane Smith", "email": "test@example.com" }
+
+pm.test("Returns 400 for missing password", function () {
+    pm.response.to.have.status(400);
+});
+```
+
+### Negative — Invalid Email Format
+
+```javascript
+// POST /api/users
+// Body: { "name": "Jane", "email": "not-an-email", "password": "SecureP@ss123" }
+
+pm.test("Returns 400 for invalid email format", function () {
+    pm.response.to.have.status(400);
+});
+
+pm.test("Error mentions email validation", function () {
+    const error = pm.response.json();
+    const msg = Array.isArray(error.message) ? error.message.join(" ") : error.message;
+    pm.expect(msg.toLowerCase()).to.satisfy(function (m) {
+        return m.includes("email") || m.includes("valid");
+    });
+});
+```
+
+### Negative — Password Too Short
+
+```javascript
+// POST /api/users
+// Body: { "name": "Jane", "email": "jane@example.com", "password": "ab" }
+
+pm.test("Returns 400 for short password", function () {
+    pm.response.to.have.status(400);
+});
+
+pm.test("Error mentions password requirements", function () {
+    const error = pm.response.json();
+    const msg = Array.isArray(error.message) ? error.message.join(" ") : error.message;
+    pm.expect(msg.toLowerCase()).to.satisfy(function (m) {
+        return m.includes("password") || m.includes("length") || m.includes("characters");
+    });
+});
+```
+
+### Negative — Empty String Values
+
+```javascript
+// POST /api/users
+// Body: { "name": "", "email": "jane@example.com", "password": "SecureP@ss123" }
+
+pm.test("Returns 400 for empty name", function () {
+    pm.response.to.have.status(400);
+});
+```
+
+```javascript
+// POST /api/users
+// Body: { "name": "   ", "email": "jane@example.com", "password": "SecureP@ss123" }
+
+pm.test("Returns 400 for whitespace-only name", function () {
+    pm.response.to.have.status(400);
+});
+```
+
+## Auth Test Patterns
+
+### Valid Token
+
+```javascript
+pm.test("Authenticated request succeeds", function () {
+    pm.response.to.have.status(200);
+});
+```
+
+### No Token
+
+```javascript
+// Remove Authorization header entirely
+
+pm.test("Returns 401 without auth token", function () {
+    pm.response.to.have.status(401);
+});
+
+pm.test("Error indicates authentication is required", function () {
+    const error = pm.response.json();
+    const msg = (error.message || error.error || "").toLowerCase();
+    pm.expect(msg).to.satisfy(function (m) {
+        return m.includes("unauthorized") || m.includes("token") || m.includes("authentication");
+    });
+});
+```
+
+### Malformed Token
+
+```javascript
+// Authorization: Bearer not-a-jwt-token
+
+pm.test("Returns 401 for malformed token", function () {
+    pm.response.to.have.status(401);
+});
+```
+
+### Expired Token
+
+```javascript
+// Authorization: Bearer <expired-jwt>
+
+pm.test("Returns 401 for expired token", function () {
+    pm.response.to.have.status(401);
+});
+
+pm.test("Error indicates token is expired", function () {
+    const error = pm.response.json();
+    const msg = (error.message || "").toLowerCase();
+    pm.expect(msg).to.satisfy(function (m) {
+        return m.includes("expired") || m.includes("invalid") || m.includes("unauthorized");
+    });
+});
+```
+
+### Insufficient Permissions (Role-Based)
+
+```javascript
+// Use a regular user token for an admin-only endpoint
+
+pm.test("Returns 403 for insufficient permissions", function () {
+    pm.response.to.have.status(403);
+});
+
+pm.test("Error indicates permission denied", function () {
+    const error = pm.response.json();
+    const msg = (error.message || error.error || "").toLowerCase();
+    pm.expect(msg).to.satisfy(function (m) {
+        return m.includes("forbidden") || m.includes("permission") || m.includes("access denied");
+    });
+});
+```
+
+## Schema Validation Patterns
+
+### Inline Schema Validation
+
+```javascript
+const userSchema = {
+    type: "object",
+    required: ["id", "name", "email", "createdAt"],
+    properties: {
+        id: { type: "string" },
+        name: { type: "string" },
+        email: { type: "string" },
+        role: { type: "string", enum: ["admin", "user", "moderator"] },
+        createdAt: { type: "string" },
+        updatedAt: { type: "string" }
+    },
+    additionalProperties: false
+};
+
+pm.test("Response matches user schema", function () {
+    pm.response.to.have.jsonSchema(userSchema);
+});
+```
+
+### List Response Schema Validation
+
+```javascript
+const paginatedSchema = {
+    type: "object",
+    required: ["data", "meta"],
+    properties: {
+        data: {
+            type: "array",
+            items: {
+                type: "object",
+                required: ["id", "name", "email"],
+                properties: {
+                    id: { type: "string" },
+                    name: { type: "string" },
+                    email: { type: "string" }
+                }
+            }
+        },
+        meta: {
+            type: "object",
+            required: ["page", "limit", "totalItems", "totalPages"],
+            properties: {
+                page: { type: "number" },
+                limit: { type: "number" },
+                totalItems: { type: "number" },
+                totalPages: { type: "number" }
+            }
+        }
+    }
+};
+
+pm.test("List response matches paginated schema", function () {
+    pm.response.to.have.jsonSchema(paginatedSchema);
+});
+```
+
+### Error Response Schema Validation
+
+```javascript
+const errorSchema = {
+    type: "object",
+    required: ["statusCode", "message", "error"],
+    properties: {
+        statusCode: { type: "number" },
+        message: {
+            oneOf: [
+                { type: "string" },
+                { type: "array", items: { type: "string" } }
+            ]
+        },
+        error: { type: "string" }
+    }
+};
+
+pm.test("Error response matches error schema", function () {
+    pm.response.to.have.jsonSchema(errorSchema);
+});
+```
+
+## Chained Test Patterns
+
+### Create -> Read -> Update -> Read -> Delete -> Read (Verify Gone)
+
+This sequence must run in order. Each step captures or uses variables.
+
+```
+Request 1: POST /api/products         → capture productId
+  Assert: 201, has id, matches input
+
+Request 2: GET /api/products/:id      → uses productId
+  Assert: 200, matches created data
+
+Request 3: PUT /api/products/:id      → uses productId
+  Assert: 200, fields updated
+
+Request 4: GET /api/products/:id      → uses productId
+  Assert: 200, reflects update
+
+Request 5: DELETE /api/products/:id   → uses productId
+  Assert: 200 or 204
+
+Request 6: GET /api/products/:id      → uses productId
+  Assert: 404
+```
+
+### Parent-Child Chain
+
+```
+Request 1: POST /api/categories       → capture categoryId
+Request 2: POST /api/products         → uses categoryId in body
+  Body: { "categoryId": "{{categoryId}}", ... }
+  Assert: 201, product.categoryId matches
+
+Request 3: GET /api/categories/:id/products → uses categoryId
+  Assert: 200, array includes created product
+
+Request 4: DELETE /api/categories/:id → uses categoryId
+  Assert: 409 (has children) OR 204 (cascade delete, verify products gone)
+```
+
+## Idempotency Test Patterns
+
+### PUT Is Idempotent
+
+```javascript
+// Run the same PUT request twice in sequence
+
+// First PUT
+pm.test("First PUT returns 200", function () {
+    pm.response.to.have.status(200);
+});
+
+// Second PUT (same data)
+pm.test("Second PUT also returns 200 (idempotent)", function () {
+    pm.response.to.have.status(200);
+});
+
+pm.test("Response is identical to first PUT", function () {
+    const response = pm.response.json();
+    pm.expect(response.name).to.eql("Updated Name");
+});
+```
+
+### DELETE Is Idempotent (or Not)
+
+```javascript
+// First DELETE
+pm.test("First DELETE succeeds", function () {
+    pm.expect(pm.response.code).to.be.oneOf([200, 204]);
+});
+
+// Second DELETE (same resource)
+pm.test("Second DELETE returns 404 (already deleted)", function () {
+    pm.response.to.have.status(404);
+});
+```
+
+## Rate Limiting Test Patterns
+
+```javascript
+pm.test("Rate limit headers are present", function () {
+    pm.response.to.have.header("X-RateLimit-Limit");
+    pm.response.to.have.header("X-RateLimit-Remaining");
+});
+
+pm.test("Rate limit remaining decreases", function () {
+    const remaining = parseInt(pm.response.headers.get("X-RateLimit-Remaining"));
+    pm.expect(remaining).to.be.a("number");
+    pm.expect(remaining).to.be.at.least(0);
+});
+
+// After exceeding the limit
+pm.test("Returns 429 when rate limit exceeded", function () {
+    pm.response.to.have.status(429);
+});
+
+pm.test("Rate limit response includes retry information", function () {
+    const response = pm.response.json();
+    const msg = (response.message || "").toLowerCase();
+    pm.expect(msg).to.satisfy(function (m) {
+        return m.includes("rate limit") || m.includes("too many requests");
+    });
+});
+```
+
+## Response Time Benchmarks
+
+```javascript
+pm.test("GET responds under 500ms", function () {
+    pm.expect(pm.response.responseTime).to.be.below(500);
+});
+
+pm.test("POST responds under 1000ms", function () {
+    pm.expect(pm.response.responseTime).to.be.below(1000);
+});
+
+pm.test("List with pagination responds under 1000ms", function () {
+    pm.expect(pm.response.responseTime).to.be.below(1000);
+});
+
+pm.test("Search/filter responds under 2000ms", function () {
+    pm.expect(pm.response.responseTime).to.be.below(2000);
+});
+```
+
+## Environment Variable Helpers
+
+### Capture and Log
+
+```javascript
+const response = pm.response.json();
+const id = response.id || response.data?.id;
+pm.environment.set("lastCreatedId", id);
+console.log("Captured ID:", id);
+```
+
+### Clear After Test Suite
+
+```javascript
+// Place in Teardown folder's test script
+pm.environment.unset("testUserId");
+pm.environment.unset("testUserEmail");
+pm.environment.unset("authToken");
+console.log("Test environment variables cleared");
+```
+
+### Generate Unique Test Data
+
+```javascript
+// Pre-request script for unique data per run
+const timestamp = Date.now();
+pm.environment.set("testEmail", `test_${timestamp}@example.com`);
+pm.environment.set("testName", `TestUser_${timestamp}`);
+pm.environment.set("testSku", `SKU-${timestamp}`);
+```