Timestamp: 10/9/2025, 8:30:30 AM
+Timestamp: 10/9/2025, 11:28:33 AM
API Spec: Test API
Postman Collection: Test Newman Collection
diff --git a/lib/postman.js b/lib/postman.js index 6c92b2c..b5afb12 100644 --- a/lib/postman.js +++ b/lib/postman.js @@ -31,11 +31,63 @@ function loadPostmanCollection(filePath) { function extractRequestsFromPostman(collection, verbose = false) { const requests = []; - function traverseItems(items, currentFolder = '') { + /** + * Extract status codes and test scripts from events + */ + function extractTestsFromEvents(events) { + const testedStatusCodes = new Set(); + let testScripts = ''; + + if (events && Array.isArray(events)) { + events.forEach(ev => { + if (ev.listen === 'test' && ev.script && ev.script.exec) { + const scriptCode = ev.script.exec.join('\n'); + testScripts += scriptCode + '\n'; // Aggregate all test scripts + + // Ищем различные паттерны + const patterns = [ + /to\.have\.status\((\d+)\)/g, + /pm\.expect\(pm\.response\.code\)\.to\.eql\((\d+)\)/g, + /pm\.response\.code\s*={1,3}\s*(\d+)/g, + /pm\.response\.status\s*={1,3}\s*(\d+)/g, + /pm\.expect\(pm\.response\.code\)\.to\.be\.oneOf\(\[([^\]]+)\]\)/g, + /to\.be\.oneOf\(\[([^\]]+)\]\)/g + ]; + patterns.forEach(regex => { + let match; + while ((match = regex.exec(scriptCode)) !== null) { + if (regex === patterns[4] || regex === patterns[5]) { + // Extract multiple codes if present (oneOf pattern) + const codesStr = match[1]; + const codesArr = codesStr.match(/\d+/g); + if (codesArr) { + codesArr.forEach(c => testedStatusCodes.add(c)); + } + } else { + testedStatusCodes.add(match[1]); + } + } + }); + } + }); + } + + return { testedStatusCodes, testScripts }; + } + + function traverseItems(items, currentFolder = '', folderTests = { testedStatusCodes: new Set(), testScripts: '' }) { items.forEach(item => { if (item.item) { - // Это папка - traverseItems(item.item, item.name); + // Это папка - извлекаем тесты из папки + const folderTestData = extractTestsFromEvents(item.event); + + // Объединяем тесты папки с родительскими тестами + const combinedFolderTests = { + testedStatusCodes: new Set([...folderTests.testedStatusCodes, ...folderTestData.testedStatusCodes]), + testScripts: folderTests.testScripts + folderTestData.testScripts + }; + + traverseItems(item.item, item.name, combinedFolderTests); } else { // Это запрос const req = item.request || {}; @@ -57,41 +109,12 @@ function extractRequestsFromPostman(collection, verbose = false) { }; } - // Ищем status-коды в тест-скриптах - let testedStatusCodes = new Set(); - let testScripts = ''; - if (item.event && Array.isArray(item.event)) { - item.event.forEach(ev => { - if (ev.listen === 'test' && ev.script && ev.script.exec) { - const scriptCode = ev.script.exec.join('\n'); - testScripts += scriptCode + '\n'; // Aggregate all test scripts - - // Ищем различные паттерны - const patterns = [ - /to\.have\.status\((\d+)\)/g, - /pm\.expect\(pm\.response\.code\)\.to\.eql\((\d+)\)/g, - /pm\.response\.code\s*={1,3}\s*(\d+)/g, - /pm\.response\.status\s*={1,3}\s*(\d+)/g, - /pm\.expect\(pm\.response\.code\)\.to\.be\.oneOf\(\[\s*([^]]+)\]/g - ]; - patterns.forEach(regex => { - let match; - while ((match = regex.exec(scriptCode)) !== null) { - if (regex === patterns[4]) { - // Extract multiple codes if present - const codesStr = match[1]; - const codesArr = codesStr.match(/\d+/g); - if (codesArr) { - codesArr.forEach(c => testedStatusCodes.add(c)); - } - } else { - testedStatusCodes.add(match[1]); - } - } - }); - } - }); - } + // Извлекаем тесты из самого запроса + const requestTestData = extractTestsFromEvents(item.event); + + // Объединяем тесты запроса с тестами папки + const combinedStatusCodes = new Set([...folderTests.testedStatusCodes, ...requestTestData.testedStatusCodes]); + const combinedTestScripts = folderTests.testScripts + requestTestData.testScripts; requests.push({ name: item.name, @@ -100,8 +123,8 @@ function extractRequestsFromPostman(collection, verbose = false) { rawUrl, queryParams, bodyInfo, - testedStatusCodes: Array.from(testedStatusCodes), - testScripts: testScripts.trim() // Include aggregated test scripts + testedStatusCodes: Array.from(combinedStatusCodes), + testScripts: combinedTestScripts.trim() // Include aggregated test scripts }); } }); diff --git a/readme.md b/readme.md index fbc2d5a..dc5f990 100644 --- a/readme.md +++ b/readme.md @@ -217,6 +217,7 @@ You will need: > **Note**: > - If using a Postman collection, make sure it includes actual test scripts that assert or check specific status codes (e.g., `pm.response.to.have.status(200)`). +> - **Folder-level tests** are fully supported: tests defined at the folder level in your Postman collection will be automatically applied to all requests within that folder, ensuring comprehensive coverage calculation. > - If using a Newman report, the tool will extract actual response codes and test results from the execution data. ### 2. Run the CLI @@ -712,6 +713,7 @@ The tool supports two types of input for test data: - **Pros**: - Contains all test logic and assertions - Can extract expected status codes from test scripts + - **Supports folder-level tests**: Tests defined at the folder level are automatically applied to all requests within that folder and its subfolders - **Cons**: - No actual execution data - Relies on parsing test scripts to understand expected outcomes @@ -728,6 +730,80 @@ The tool supports two types of input for test data: **Recommendation**: Use Newman reports when possible for more accurate coverage analysis, especially in CI/CD pipelines where collections are actually executed. +### Folder-Level Tests in Postman Collections + +**swagger-coverage-cli** fully supports **folder-level tests** in Postman collections. Tests defined at the folder level are automatically applied to all requests within that folder and its subfolders, making it easy to apply common test assertions across multiple endpoints. + +#### How It Works + +When you define tests at the folder level in your Postman collection: +1. The tests are extracted from the folder's event scripts +2. Status codes and assertions are identified from the test scripts +3. These tests are automatically combined with any request-level tests +4. All requests within the folder (and nested folders) inherit these tests + +#### Example + +Consider this Postman collection structure: + +```json +{ + "name": "Users API", + "item": [ + { + "name": "Get User", + "request": { "method": "GET", "url": "/users/1" } + }, + { + "name": "Create User", + "request": { "method": "POST", "url": "/users" } + } + ], + "event": [ + { + "listen": "test", + "script": { + "exec": [ + "pm.test('Status code is 200 or 201', function () {", + " pm.expect(pm.response.code).to.be.oneOf([200, 201]);", + "});" + ] + } + } + ] +} +``` + +In this example: +- The folder "Users API" has a test that checks for status codes 200 or 201 +- **Both** "Get User" and "Create User" requests will inherit these status codes +- This means both endpoints will be counted as testing status codes 200 and 201 + +#### Benefits + +- **Reduced duplication**: Define common tests once at the folder level +- **Better coverage**: Ensures all requests within a folder test common scenarios +- **Easier maintenance**: Update folder-level tests to affect all child requests +- **Nested support**: Folder-level tests are inherited through multiple levels of nesting + +#### Supported Test Patterns + +Folder-level tests support the same patterns as request-level tests: +- `pm.response.to.have.status(200)` +- `pm.expect(pm.response.code).to.eql(201)` +- `pm.expect(pm.response.code).to.be.oneOf([200, 201, 204])` +- And other common Postman test assertions + +#### Edge Cases Handled + +The folder-level test feature handles various edge cases: +- **Empty folders**: Folders with no requests are handled gracefully +- **Deep nesting**: Supports unlimited levels of nested folders with test inheritance at each level +- **Missing events**: Requests or folders without event properties work correctly +- **Mixed patterns**: Multiple test patterns in the same folder or request are combined +- **Null/undefined events**: Folders with null or undefined event properties are handled safely +- **Non-test events**: Only "test" events are processed; other events (like "prerequest") are ignored + ### Using CSV for Documentation In addition to traditional OpenAPI/Swagger specifications, **swagger-coverage-cli** supports API documentation provided in a **CSV** format. This allows for a more flexible and easily editable documentation process, especially for teams that prefer spreadsheet-based documentation. diff --git a/test/postman.test.js b/test/postman.test.js index 4c31838..3d13f0b 100644 --- a/test/postman.test.js +++ b/test/postman.test.js @@ -37,4 +37,651 @@ describe('Postman Module', () => { expect(requests[0].name).toBe('Test Request'); expect(requests[0].method).toBe('get'); }); + + test('extractRequestsFromPostman should extract folder-level tests and apply them to all requests', () => { + const collection = { + item: [ + { + name: 'API v1', + item: [ + { + name: 'Get User', + request: { + method: 'GET', + url: 'https://api.example.com/users/1' + } + }, + { + name: 'Create User', + request: { + method: 'POST', + url: 'https://api.example.com/users' + } + } + ], + event: [ + { + listen: 'test', + script: { + exec: [ + 'pm.test("Status code is 200 or 201", function () {', + ' pm.expect(pm.response.code).to.be.oneOf([200, 201]);', + '});' + ] + } + } + ] + } + ] + }; + + const requests = extractRequestsFromPostman(collection); + expect(requests.length).toBe(2); + + // Both requests should have the folder-level status codes + expect(requests[0].testedStatusCodes).toContain('200'); + expect(requests[0].testedStatusCodes).toContain('201'); + expect(requests[0].testScripts).toContain('pm.expect(pm.response.code).to.be.oneOf([200, 201])'); + + expect(requests[1].testedStatusCodes).toContain('200'); + expect(requests[1].testedStatusCodes).toContain('201'); + expect(requests[1].testScripts).toContain('pm.expect(pm.response.code).to.be.oneOf([200, 201])'); + }); + + test('extractRequestsFromPostman should combine folder-level and request-level tests', () => { + const collection = { + item: [ + { + name: 'Users', + item: [ + { + name: 'Get User', + request: { + method: 'GET', + url: 'https://api.example.com/users/1' + }, + event: [ + { + listen: 'test', + script: { + exec: [ + 'pm.test("Status code is 200", function () {', + ' pm.response.to.have.status(200);', + '});' + ] + } + } + ] + } + ], + event: [ + { + listen: 'test', + script: { + exec: [ + 'pm.test("Response time is acceptable", function () {', + ' pm.expect(pm.response.responseTime).to.be.below(500);', + '});' + ] + } + } + ] + } + ] + }; + + const requests = extractRequestsFromPostman(collection); + expect(requests.length).toBe(1); + + // Should have status code from request-level test + expect(requests[0].testedStatusCodes).toContain('200'); + + // Should have both folder-level and request-level test scripts + expect(requests[0].testScripts).toContain('Response time is acceptable'); + expect(requests[0].testScripts).toContain('Status code is 200'); + }); + + test('extractRequestsFromPostman should handle nested folders with tests', () => { + const collection = { + item: [ + { + name: 'API', + item: [ + { + name: 'Users', + item: [ + { + name: 'Get User', + request: { + method: 'GET', + url: 'https://api.example.com/users/1' + } + } + ], + event: [ + { + listen: 'test', + script: { + exec: [ + 'pm.test("Status code is 200", function () {', + ' pm.response.to.have.status(200);', + '});' + ] + } + } + ] + } + ], + event: [ + { + listen: 'test', + script: { + exec: [ + 'pm.test("Has valid JSON", function () {', + ' pm.response.to.be.json;', + '});' + ] + } + } + ] + } + ] + }; + + const requests = extractRequestsFromPostman(collection); + expect(requests.length).toBe(1); + + // Should have status code from nested folder test + expect(requests[0].testedStatusCodes).toContain('200'); + + // Should have both parent and nested folder test scripts + expect(requests[0].testScripts).toContain('Has valid JSON'); + expect(requests[0].testScripts).toContain('Status code is 200'); + }); + + test('extractRequestsFromPostman should handle folders without tests', () => { + const collection = { + item: [ + { + name: 'Users', + item: [ + { + name: 'Get User', + request: { + method: 'GET', + url: 'https://api.example.com/users/1' + }, + event: [ + { + listen: 'test', + script: { + exec: [ + 'pm.test("Status code is 200", function () {', + ' pm.response.to.have.status(200);', + '});' + ] + } + } + ] + } + ] + // No folder-level event + } + ] + }; + + const requests = extractRequestsFromPostman(collection); + expect(requests.length).toBe(1); + expect(requests[0].testedStatusCodes).toContain('200'); + expect(requests[0].testScripts).toContain('Status code is 200'); + }); + + test('extractRequestsFromPostman should extract status codes with alternative oneOf pattern', () => { + const collection = { + item: [ + { + name: 'Test Request', + request: { + method: 'GET', + url: 'https://api.example.com/test' + }, + event: [ + { + listen: 'test', + script: { + exec: [ + 'pm.response.to.be.oneOf([200, 201, 204]);' + ] + } + } + ] + } + ] + }; + + const requests = extractRequestsFromPostman(collection); + expect(requests.length).toBe(1); + expect(requests[0].testedStatusCodes).toContain('200'); + expect(requests[0].testedStatusCodes).toContain('201'); + expect(requests[0].testedStatusCodes).toContain('204'); + }); + + test('extractRequestsFromPostman should handle multiple folders with different tests', () => { + const collection = { + item: [ + { + name: 'Public API', + item: [ + { + name: 'Health Check', + request: { + method: 'GET', + url: 'https://api.example.com/health' + } + } + ], + event: [ + { + listen: 'test', + script: { + exec: [ + 'pm.response.to.have.status(200);' + ] + } + } + ] + }, + { + name: 'Admin API', + item: [ + { + name: 'Get Settings', + request: { + method: 'GET', + url: 'https://api.example.com/admin/settings' + } + } + ], + event: [ + { + listen: 'test', + script: { + exec: [ + 'pm.expect(pm.response.code).to.eql(200);', + 'pm.test("Has authorization", function () {', + ' pm.response.to.have.header("Authorization");', + '});' + ] + } + } + ] + } + ] + }; + + const requests = extractRequestsFromPostman(collection); + expect(requests.length).toBe(2); + + // First request should have status code 200 from Public API folder + expect(requests[0].testedStatusCodes).toContain('200'); + expect(requests[0].testScripts).toContain('pm.response.to.have.status(200)'); + + // Second request should have status code 200 from Admin API folder + expect(requests[1].testedStatusCodes).toContain('200'); + expect(requests[1].testScripts).toContain('pm.expect(pm.response.code).to.eql(200)'); + expect(requests[1].testScripts).toContain('Has authorization'); + }); + + // Edge case tests + test('extractRequestsFromPostman should handle empty folders gracefully', () => { + const collection = { + item: [ + { + name: 'Empty Folder', + item: [], + event: [ + { + listen: 'test', + script: { + exec: ['pm.response.to.have.status(200);'] + } + } + ] + }, + { + name: 'Regular Request', + request: { + method: 'GET', + url: 'https://api.example.com/test' + } + } + ] + }; + + const requests = extractRequestsFromPostman(collection); + expect(requests.length).toBe(1); + expect(requests[0].name).toBe('Regular Request'); + }); + + test('extractRequestsFromPostman should handle folders containing only subfolders', () => { + const collection = { + item: [ + { + name: 'Parent Folder', + item: [ + { + name: 'Child Folder', + item: [ + { + name: 'Deep Request', + request: { + method: 'GET', + url: 'https://api.example.com/deep' + } + } + ], + event: [ + { + listen: 'test', + script: { + exec: ['pm.response.to.have.status(200);'] + } + } + ] + } + ], + event: [ + { + listen: 'test', + script: { + exec: ['pm.expect(pm.response.code).to.eql(201);'] + } + } + ] + } + ] + }; + + const requests = extractRequestsFromPostman(collection); + expect(requests.length).toBe(1); + expect(requests[0].testedStatusCodes).toContain('200'); + expect(requests[0].testedStatusCodes).toContain('201'); + }); + + test('extractRequestsFromPostman should handle requests with no event property', () => { + const collection = { + item: [ + { + name: 'Folder with tests', + item: [ + { + name: 'Request without events', + request: { + method: 'GET', + url: 'https://api.example.com/test' + } + // No event property at all + } + ], + event: [ + { + listen: 'test', + script: { + exec: ['pm.response.to.have.status(200);'] + } + } + ] + } + ] + }; + + const requests = extractRequestsFromPostman(collection); + expect(requests.length).toBe(1); + expect(requests[0].testedStatusCodes).toContain('200'); + }); + + test('extractRequestsFromPostman should handle empty event arrays', () => { + const collection = { + item: [ + { + name: 'Folder', + item: [ + { + name: 'Request', + request: { + method: 'GET', + url: 'https://api.example.com/test' + }, + event: [] // Empty array + } + ], + event: [] // Empty array + } + ] + }; + + const requests = extractRequestsFromPostman(collection); + expect(requests.length).toBe(1); + expect(requests[0].testedStatusCodes).toEqual([]); + expect(requests[0].testScripts).toBe(''); + }); + + test('extractRequestsFromPostman should ignore non-test events', () => { + const collection = { + item: [ + { + name: 'Folder', + item: [ + { + name: 'Request', + request: { + method: 'GET', + url: 'https://api.example.com/test' + } + } + ], + event: [ + { + listen: 'prerequest', + script: { + exec: ['console.log("This should be ignored");'] + } + }, + { + listen: 'test', + script: { + exec: ['pm.response.to.have.status(200);'] + } + } + ] + } + ] + }; + + const requests = extractRequestsFromPostman(collection); + expect(requests.length).toBe(1); + expect(requests[0].testedStatusCodes).toContain('200'); + expect(requests[0].testScripts).not.toContain('This should be ignored'); + }); + + test('extractRequestsFromPostman should handle deeply nested folders (3+ levels)', () => { + const collection = { + item: [ + { + name: 'Level 1', + item: [ + { + name: 'Level 2', + item: [ + { + name: 'Level 3', + item: [ + { + name: 'Deep Request', + request: { + method: 'GET', + url: 'https://api.example.com/deep' + } + } + ], + event: [ + { + listen: 'test', + script: { + exec: ['pm.response.to.have.status(200);'] + } + } + ] + } + ], + event: [ + { + listen: 'test', + script: { + exec: ['pm.expect(pm.response.code).to.eql(201);'] + } + } + ] + } + ], + event: [ + { + listen: 'test', + script: { + exec: ['pm.expect(pm.response.code).to.be.oneOf([202, 204]);'] + } + } + ] + } + ] + }; + + const requests = extractRequestsFromPostman(collection); + expect(requests.length).toBe(1); + // Should inherit all status codes from all levels + expect(requests[0].testedStatusCodes).toContain('200'); + expect(requests[0].testedStatusCodes).toContain('201'); + expect(requests[0].testedStatusCodes).toContain('202'); + expect(requests[0].testedStatusCodes).toContain('204'); + }); + + test('extractRequestsFromPostman should handle various status code assertion patterns', () => { + const collection = { + item: [ + { + name: 'Test Pattern 1', + request: { + method: 'GET', + url: 'https://api.example.com/test1' + }, + event: [ + { + listen: 'test', + script: { + exec: ['pm.response.code === 200'] + } + } + ] + }, + { + name: 'Test Pattern 2', + request: { + method: 'GET', + url: 'https://api.example.com/test2' + }, + event: [ + { + listen: 'test', + script: { + exec: ['pm.response.status === 201'] + } + } + ] + } + ] + }; + + const requests = extractRequestsFromPostman(collection); + expect(requests.length).toBe(2); + expect(requests[0].testedStatusCodes).toContain('200'); + expect(requests[1].testedStatusCodes).toContain('201'); + }); + + test('extractRequestsFromPostman should handle mixed test patterns in same folder', () => { + const collection = { + item: [ + { + name: 'Mixed Patterns Folder', + item: [ + { + name: 'Request', + request: { + method: 'GET', + url: 'https://api.example.com/test' + } + } + ], + event: [ + { + listen: 'test', + script: { + exec: [ + 'pm.response.to.have.status(200);', + 'pm.expect(pm.response.code).to.eql(201);', + 'pm.expect(pm.response.code).to.be.oneOf([202, 203]);', + 'pm.response.code === 204' + ] + } + } + ] + } + ] + }; + + const requests = extractRequestsFromPostman(collection); + expect(requests.length).toBe(1); + expect(requests[0].testedStatusCodes).toContain('200'); + expect(requests[0].testedStatusCodes).toContain('201'); + expect(requests[0].testedStatusCodes).toContain('202'); + expect(requests[0].testedStatusCodes).toContain('203'); + expect(requests[0].testedStatusCodes).toContain('204'); + }); + + test('extractRequestsFromPostman should handle folders with undefined or null event properties', () => { + const collection = { + item: [ + { + name: 'Folder with undefined event', + item: [ + { + name: 'Request', + request: { + method: 'GET', + url: 'https://api.example.com/test' + } + } + ], + event: undefined + }, + { + name: 'Folder with null event', + item: [ + { + name: 'Request 2', + request: { + method: 'POST', + url: 'https://api.example.com/test2' + } + } + ], + event: null + } + ] + }; + + const requests = extractRequestsFromPostman(collection); + expect(requests.length).toBe(2); + expect(requests[0].testedStatusCodes).toEqual([]); + expect(requests[1].testedStatusCodes).toEqual([]); + }); }); \ No newline at end of file