mcp-openapi-schema-explorer 1.0.0

package/test/__tests__/unit/handlers/component-detail-handler.test.ts

@@ -0,0 +1,241 @@
+import { OpenAPIV3 } from 'openapi-types';
+import { ComponentDetailHandler } from '../../../../src/handlers/component-detail-handler';
+import { SpecLoaderService } from '../../../../src/types';
+import { IFormatter, JsonFormatter } from '../../../../src/services/formatters';
+import { ResourceTemplate } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { Variables } from '@modelcontextprotocol/sdk/shared/uriTemplate.js';
+import { suppressExpectedConsoleError } from '../../../utils/console-helpers';
+
+// Mocks
+const mockGetTransformedSpec = jest.fn();
+const mockSpecLoader: SpecLoaderService = {
+  getSpec: jest.fn(),
+  getTransformedSpec: mockGetTransformedSpec,
+};
+
+const mockFormatter: IFormatter = new JsonFormatter();
+
+// Sample Data
+const userSchema: OpenAPIV3.SchemaObject = {
+  type: 'object',
+  properties: { name: { type: 'string' } },
+};
+const errorSchema: OpenAPIV3.SchemaObject = {
+  type: 'object',
+  properties: { message: { type: 'string' } },
+};
+const limitParam: OpenAPIV3.ParameterObject = {
+  name: 'limit',
+  in: 'query',
+  schema: { type: 'integer' },
+};
+
+const sampleSpec: OpenAPIV3.Document = {
+  openapi: '3.0.3',
+  info: { title: 'Test API', version: '1.0.0' },
+  paths: {},
+  components: {
+    schemas: {
+      User: userSchema,
+      Error: errorSchema,
+    },
+    parameters: {
+      limitParam: limitParam,
+    },
+    // No securitySchemes defined
+  },
+};
+
+describe('ComponentDetailHandler', () => {
+  let handler: ComponentDetailHandler;
+
+  beforeEach(() => {
+    handler = new ComponentDetailHandler(mockSpecLoader, mockFormatter);
+    mockGetTransformedSpec.mockReset();
+    mockGetTransformedSpec.mockResolvedValue(sampleSpec); // Default mock
+  });
+
+  it('should return the correct template', () => {
+    const template = handler.getTemplate();
+    expect(template).toBeInstanceOf(ResourceTemplate);
+    expect(template.uriTemplate.toString()).toBe('openapi://components/{type}/{name*}');
+  });
+
+  describe('handleRequest', () => {
+    const mockExtra = { signal: new AbortController().signal };
+
+    it('should return detail for a single valid component (schema)', async () => {
+      const variables: Variables = { type: 'schemas', name: 'User' }; // Use 'name' key
+      const uri = new URL('openapi://components/schemas/User');
+
+      const result = await handler.handleRequest(uri, variables, mockExtra);
+
+      expect(mockGetTransformedSpec).toHaveBeenCalledWith({
+        resourceType: 'schema',
+        format: 'openapi',
+      });
+      expect(result.contents).toHaveLength(1);
+      expect(result.contents[0]).toEqual({
+        uri: 'openapi://components/schemas/User',
+        mimeType: 'application/json',
+        text: JSON.stringify(userSchema, null, 2),
+        isError: false,
+      });
+    });
+
+    it('should return detail for a single valid component (parameter)', async () => {
+      const variables: Variables = { type: 'parameters', name: 'limitParam' };
+      const uri = new URL('openapi://components/parameters/limitParam');
+
+      const result = await handler.handleRequest(uri, variables, mockExtra);
+
+      expect(result.contents).toHaveLength(1);
+      expect(result.contents[0]).toEqual({
+        uri: 'openapi://components/parameters/limitParam',
+        mimeType: 'application/json',
+        text: JSON.stringify(limitParam, null, 2),
+        isError: false,
+      });
+    });
+
+    it('should return details for multiple valid components (array input)', async () => {
+      const variables: Variables = { type: 'schemas', name: ['User', 'Error'] }; // Use 'name' key with array
+      const uri = new URL('openapi://components/schemas/User,Error'); // URI might not reflect array input
+
+      const result = await handler.handleRequest(uri, variables, mockExtra);
+
+      expect(result.contents).toHaveLength(2);
+      expect(result.contents).toContainEqual({
+        uri: 'openapi://components/schemas/User',
+        mimeType: 'application/json',
+        text: JSON.stringify(userSchema, null, 2),
+        isError: false,
+      });
+      expect(result.contents).toContainEqual({
+        uri: 'openapi://components/schemas/Error',
+        mimeType: 'application/json',
+        text: JSON.stringify(errorSchema, null, 2),
+        isError: false,
+      });
+    });
+
+    it('should return error for invalid component type', async () => {
+      const variables: Variables = { type: 'invalidType', name: 'SomeName' };
+      const uri = new URL('openapi://components/invalidType/SomeName');
+      const expectedLogMessage = /Invalid component type: invalidType/;
+
+      const result = await suppressExpectedConsoleError(expectedLogMessage, () =>
+        handler.handleRequest(uri, variables, mockExtra)
+      );
+
+      expect(result.contents).toHaveLength(1);
+      expect(result.contents[0]).toEqual({
+        uri: 'openapi://components/invalidType/SomeName',
+        mimeType: 'text/plain',
+        text: 'Invalid component type: invalidType',
+        isError: true,
+      });
+      expect(mockGetTransformedSpec).not.toHaveBeenCalled();
+    });
+
+    it('should return error for non-existent component type in spec', async () => {
+      const variables: Variables = { type: 'securitySchemes', name: 'apiKey' };
+      const uri = new URL('openapi://components/securitySchemes/apiKey');
+      const expectedLogMessage = /Component type "securitySchemes" not found/;
+
+      const result = await suppressExpectedConsoleError(expectedLogMessage, () =>
+        handler.handleRequest(uri, variables, mockExtra)
+      );
+
+      expect(result.contents).toHaveLength(1);
+      // Expect the specific error message from getValidatedComponentMap
+      expect(result.contents[0]).toEqual({
+        uri: 'openapi://components/securitySchemes/apiKey',
+        mimeType: 'text/plain',
+        text: 'Component type "securitySchemes" not found in the specification. Available types: schemas, parameters',
+        isError: true,
+      });
+    });
+
+    it('should return error for non-existent component name', async () => {
+      const variables: Variables = { type: 'schemas', name: 'NonExistent' };
+      const uri = new URL('openapi://components/schemas/NonExistent');
+      const expectedLogMessage = /None of the requested names \(NonExistent\) are valid/;
+
+      const result = await suppressExpectedConsoleError(expectedLogMessage, () =>
+        handler.handleRequest(uri, variables, mockExtra)
+      );
+
+      expect(result.contents).toHaveLength(1);
+      // Expect the specific error message from getValidatedComponentDetails
+      expect(result.contents[0]).toEqual({
+        uri: 'openapi://components/schemas/NonExistent',
+        mimeType: 'text/plain',
+        // Expect sorted names: Error, User
+        text: 'None of the requested names (NonExistent) are valid for component type "schemas". Available names: Error, User',
+        isError: true,
+      });
+    });
+
+    // Remove test for mix of valid/invalid names, as getValidatedComponentDetails throws now
+    // it('should handle mix of valid and invalid component names', async () => { ... });
+
+    it('should handle empty name array', async () => {
+      const variables: Variables = { type: 'schemas', name: [] };
+      const uri = new URL('openapi://components/schemas/');
+      const expectedLogMessage = /No valid component name specified/;
+
+      const result = await suppressExpectedConsoleError(expectedLogMessage, () =>
+        handler.handleRequest(uri, variables, mockExtra)
+      );
+
+      expect(result.contents).toHaveLength(1);
+      expect(result.contents[0]).toEqual({
+        uri: 'openapi://components/schemas/',
+        mimeType: 'text/plain',
+        text: 'No valid component name specified.',
+        isError: true,
+      });
+    });
+
+    it('should handle spec loading errors', async () => {
+      const error = new Error('Spec load failed');
+      mockGetTransformedSpec.mockRejectedValue(error);
+      const variables: Variables = { type: 'schemas', name: 'User' };
+      const uri = new URL('openapi://components/schemas/User');
+      const expectedLogMessage = /Spec load failed/;
+
+      const result = await suppressExpectedConsoleError(expectedLogMessage, () =>
+        handler.handleRequest(uri, variables, mockExtra)
+      );
+
+      expect(result.contents).toHaveLength(1);
+      expect(result.contents[0]).toEqual({
+        uri: 'openapi://components/schemas/User',
+        mimeType: 'text/plain',
+        text: 'Spec load failed',
+        isError: true,
+      });
+    });
+
+    it('should handle non-OpenAPI v3 spec', async () => {
+      const invalidSpec = { swagger: '2.0', info: {} };
+      mockGetTransformedSpec.mockResolvedValue(invalidSpec as unknown as OpenAPIV3.Document);
+      const variables: Variables = { type: 'schemas', name: 'User' };
+      const uri = new URL('openapi://components/schemas/User');
+      const expectedLogMessage = /Only OpenAPI v3 specifications are supported/;
+
+      const result = await suppressExpectedConsoleError(expectedLogMessage, () =>
+        handler.handleRequest(uri, variables, mockExtra)
+      );
+
+      expect(result.contents).toHaveLength(1);
+      expect(result.contents[0]).toEqual({
+        uri: 'openapi://components/schemas/User',
+        mimeType: 'text/plain',
+        text: 'Only OpenAPI v3 specifications are supported',
+        isError: true,
+      });
+    });
+  });
+});

package/test/__tests__/unit/handlers/component-map-handler.test.ts

@@ -0,0 +1,187 @@
+import { OpenAPIV3 } from 'openapi-types';
+import { ComponentMapHandler } from '../../../../src/handlers/component-map-handler';
+import { SpecLoaderService } from '../../../../src/types';
+import { IFormatter, JsonFormatter } from '../../../../src/services/formatters';
+import { ResourceTemplate } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { Variables } from '@modelcontextprotocol/sdk/shared/uriTemplate.js';
+import { suppressExpectedConsoleError } from '../../../utils/console-helpers';
+
+// Mocks
+const mockGetTransformedSpec = jest.fn();
+const mockSpecLoader: SpecLoaderService = {
+  getSpec: jest.fn(),
+  getTransformedSpec: mockGetTransformedSpec,
+};
+
+const mockFormatter: IFormatter = new JsonFormatter(); // Needed for context
+
+// Sample Data
+const sampleSpec: OpenAPIV3.Document = {
+  openapi: '3.0.3',
+  info: { title: 'Test API', version: '1.0.0' },
+  paths: {},
+  components: {
+    schemas: {
+      User: { type: 'object', properties: { name: { type: 'string' } } },
+      Error: { type: 'object', properties: { message: { type: 'string' } } },
+    },
+    parameters: {
+      limitParam: { name: 'limit', in: 'query', schema: { type: 'integer' } },
+    },
+    examples: {}, // Empty type
+  },
+};
+
+describe('ComponentMapHandler', () => {
+  let handler: ComponentMapHandler;
+
+  beforeEach(() => {
+    handler = new ComponentMapHandler(mockSpecLoader, mockFormatter);
+    mockGetTransformedSpec.mockReset();
+    mockGetTransformedSpec.mockResolvedValue(sampleSpec); // Default mock
+  });
+
+  it('should return the correct template', () => {
+    const template = handler.getTemplate();
+    expect(template).toBeInstanceOf(ResourceTemplate);
+    expect(template.uriTemplate.toString()).toBe('openapi://components/{type}');
+  });
+
+  describe('handleRequest (List Component Names)', () => {
+    const mockExtra = { signal: new AbortController().signal };
+
+    it('should list names for a valid component type (schemas)', async () => {
+      const variables: Variables = { type: 'schemas' };
+      const uri = new URL('openapi://components/schemas');
+
+      const result = await handler.handleRequest(uri, variables, mockExtra);
+
+      expect(mockGetTransformedSpec).toHaveBeenCalledWith({
+        resourceType: 'schema',
+        format: 'openapi',
+      });
+      expect(result.contents).toHaveLength(1);
+      expect(result.contents[0]).toMatchObject({
+        uri: 'openapi://components/schemas',
+        mimeType: 'text/plain',
+        isError: false,
+      });
+      expect(result.contents[0].text).toContain('Available schemas:');
+      expect(result.contents[0].text).toMatch(/-\sError\n/); // Sorted
+      expect(result.contents[0].text).toMatch(/-\sUser\n/);
+      expect(result.contents[0].text).toContain("Hint: Use 'openapi://components/schemas/{name}'");
+    });
+
+    it('should list names for another valid type (parameters)', async () => {
+      const variables: Variables = { type: 'parameters' };
+      const uri = new URL('openapi://components/parameters');
+
+      const result = await handler.handleRequest(uri, variables, mockExtra);
+
+      expect(result.contents).toHaveLength(1);
+      expect(result.contents[0]).toMatchObject({
+        uri: 'openapi://components/parameters',
+        mimeType: 'text/plain',
+        isError: false,
+      });
+      expect(result.contents[0].text).toContain('Available parameters:');
+      expect(result.contents[0].text).toMatch(/-\slimitParam\n/);
+      expect(result.contents[0].text).toContain(
+        "Hint: Use 'openapi://components/parameters/{name}'"
+      );
+    });
+
+    it('should handle component type with no components defined (examples)', async () => {
+      const variables: Variables = { type: 'examples' };
+      const uri = new URL('openapi://components/examples');
+
+      const result = await handler.handleRequest(uri, variables, mockExtra);
+
+      expect(result.contents).toHaveLength(1);
+      expect(result.contents[0]).toEqual({
+        uri: 'openapi://components/examples',
+        mimeType: 'text/plain',
+        text: 'No components of type "examples" found.',
+        isError: true, // Treat as error because map exists but is empty
+      });
+    });
+
+    it('should handle component type not present in spec (securitySchemes)', async () => {
+      const variables: Variables = { type: 'securitySchemes' };
+      const uri = new URL('openapi://components/securitySchemes');
+      const expectedLogMessage = /Component type "securitySchemes" not found/;
+
+      const result = await suppressExpectedConsoleError(expectedLogMessage, () =>
+        handler.handleRequest(uri, variables, mockExtra)
+      );
+
+      expect(result.contents).toHaveLength(1);
+      // Expect the specific error message from getValidatedComponentMap
+      expect(result.contents[0]).toEqual({
+        uri: 'openapi://components/securitySchemes',
+        mimeType: 'text/plain',
+        text: 'Component type "securitySchemes" not found in the specification. Available types: schemas, parameters, examples',
+        isError: true,
+      });
+    });
+
+    it('should return error for invalid component type', async () => {
+      const variables: Variables = { type: 'invalidType' };
+      const uri = new URL('openapi://components/invalidType');
+      const expectedLogMessage = /Invalid component type: invalidType/;
+
+      const result = await suppressExpectedConsoleError(expectedLogMessage, () =>
+        handler.handleRequest(uri, variables, mockExtra)
+      );
+
+      expect(result.contents).toHaveLength(1);
+      expect(result.contents[0]).toEqual({
+        uri: 'openapi://components/invalidType',
+        mimeType: 'text/plain',
+        text: 'Invalid component type: invalidType',
+        isError: true,
+      });
+      expect(mockGetTransformedSpec).not.toHaveBeenCalled(); // Should fail before loading spec
+    });
+
+    it('should handle spec loading errors', async () => {
+      const error = new Error('Spec load failed');
+      mockGetTransformedSpec.mockRejectedValue(error);
+      const variables: Variables = { type: 'schemas' };
+      const uri = new URL('openapi://components/schemas');
+      const expectedLogMessage = /Spec load failed/;
+
+      const result = await suppressExpectedConsoleError(expectedLogMessage, () =>
+        handler.handleRequest(uri, variables, mockExtra)
+      );
+
+      expect(result.contents).toHaveLength(1);
+      expect(result.contents[0]).toEqual({
+        uri: 'openapi://components/schemas',
+        mimeType: 'text/plain',
+        text: 'Spec load failed',
+        isError: true,
+      });
+    });
+
+    it('should handle non-OpenAPI v3 spec', async () => {
+      const invalidSpec = { swagger: '2.0', info: {} };
+      mockGetTransformedSpec.mockResolvedValue(invalidSpec as unknown as OpenAPIV3.Document);
+      const variables: Variables = { type: 'schemas' };
+      const uri = new URL('openapi://components/schemas');
+      const expectedLogMessage = /Only OpenAPI v3 specifications are supported/;
+
+      const result = await suppressExpectedConsoleError(expectedLogMessage, () =>
+        handler.handleRequest(uri, variables, mockExtra)
+      );
+
+      expect(result.contents).toHaveLength(1);
+      expect(result.contents[0]).toEqual({
+        uri: 'openapi://components/schemas',
+        mimeType: 'text/plain',
+        text: 'Only OpenAPI v3 specifications are supported',
+        isError: true,
+      });
+    });
+  });
+});

package/test/__tests__/unit/handlers/handler-utils.test.ts

@@ -0,0 +1,255 @@
+import { OpenAPIV3 } from 'openapi-types';
+import {
+  getValidatedPathItem,
+  getValidatedOperations,
+  getValidatedComponentMap,
+  getValidatedComponentDetails,
+  // We might also test formatResults and isOpenAPIV3 if needed, but focus on new helpers first
+} from '../../../../src/handlers/handler-utils.js'; // Adjust path as needed
+
+// --- Mocks and Fixtures ---
+
+const mockSpec: OpenAPIV3.Document = {
+  openapi: '3.0.0',
+  info: { title: 'Test API', version: '1.0.0' },
+  paths: {
+    '/users': {
+      get: { responses: { '200': { description: 'OK' } } },
+      post: { responses: { '201': { description: 'Created' } } },
+    },
+    '/users/{id}': {
+      get: { responses: { '200': { description: 'OK' } } },
+      delete: { responses: { '204': { description: 'No Content' } } },
+      parameters: [{ name: 'id', in: 'path', required: true, schema: { type: 'string' } }],
+    },
+    '/items': {
+      // Path item with no standard methods
+      description: 'Collection of items',
+      parameters: [],
+    },
+  },
+  components: {
+    schemas: {
+      User: { type: 'object', properties: { id: { type: 'string' } } },
+      Error: { type: 'object', properties: { message: { type: 'string' } } },
+    },
+    responses: {
+      NotFound: { description: 'Resource not found' },
+    },
+    // Intentionally missing 'parameters' section for testing
+  },
+};
+
+const mockSpecNoPaths: OpenAPIV3.Document = {
+  openapi: '3.0.0',
+  info: { title: 'Test API', version: '1.0.0' },
+  paths: {}, // Empty paths
+  components: {},
+};
+
+const mockSpecNoComponents: OpenAPIV3.Document = {
+  openapi: '3.0.0',
+  info: { title: 'Test API', version: '1.0.0' },
+  paths: { '/ping': { get: { responses: { '200': { description: 'OK' } } } } },
+  // No components section
+};
+
+// --- Tests ---
+
+describe('Handler Utils', () => {
+  // --- getValidatedPathItem ---
+  describe('getValidatedPathItem', () => {
+    it('should return the path item object for a valid path', () => {
+      const pathItem = getValidatedPathItem(mockSpec, '/users');
+      expect(pathItem).toBeDefined();
+      expect(pathItem).toHaveProperty('get');
+      expect(pathItem).toHaveProperty('post');
+    });
+
+    it('should return the path item object for a path with parameters', () => {
+      const pathItem = getValidatedPathItem(mockSpec, '/users/{id}');
+      expect(pathItem).toBeDefined();
+      expect(pathItem).toHaveProperty('get');
+      expect(pathItem).toHaveProperty('delete');
+      expect(pathItem).toHaveProperty('parameters');
+    });
+
+    it('should throw Error if path is not found', () => {
+      expect(() => getValidatedPathItem(mockSpec, '/nonexistent')).toThrow(
+        new Error('Path "/nonexistent" not found in the specification.')
+      );
+    });
+
+    it('should throw Error if spec has no paths object', () => {
+      const specWithoutPaths = { ...mockSpec, paths: undefined };
+      // @ts-expect-error - Intentionally passing spec with undefined paths to test error handling
+      expect(() => getValidatedPathItem(specWithoutPaths, '/users')).toThrow(
+        new Error('Specification does not contain any paths.')
+      );
+    });
+
+    it('should throw Error if spec has empty paths object', () => {
+      expect(() => getValidatedPathItem(mockSpecNoPaths, '/users')).toThrow(
+        new Error('Path "/users" not found in the specification.')
+      );
+    });
+  });
+
+  // --- getValidatedOperations ---
+  describe('getValidatedOperations', () => {
+    const usersPathItem = mockSpec.paths['/users'] as OpenAPIV3.PathItemObject;
+    const userIdPathItem = mockSpec.paths['/users/{id}'] as OpenAPIV3.PathItemObject;
+    const itemsPathItem = mockSpec.paths['/items'] as OpenAPIV3.PathItemObject;
+
+    it('should return valid requested methods when all exist', () => {
+      const validMethods = getValidatedOperations(usersPathItem, ['get', 'post'], '/users');
+      expect(validMethods).toEqual(['get', 'post']);
+    });
+
+    it('should return valid requested methods when some exist', () => {
+      const validMethods = getValidatedOperations(usersPathItem, ['get', 'put', 'post'], '/users');
+      expect(validMethods).toEqual(['get', 'post']);
+    });
+
+    it('should return valid requested methods ignoring case', () => {
+      const validMethods = getValidatedOperations(usersPathItem, ['GET', 'POST'], '/users');
+      // Note: the helper expects lowercase input, but the internal map uses lowercase keys
+      expect(validMethods).toEqual(['GET', 'POST']); // It returns the original case of valid inputs
+    });
+
+    it('should return only the valid method when one exists', () => {
+      const validMethods = getValidatedOperations(
+        userIdPathItem,
+        ['delete', 'patch'],
+        '/users/{id}'
+      );
+      expect(validMethods).toEqual(['delete']);
+    });
+
+    it('should throw Error if no requested methods are valid', () => {
+      expect(() => getValidatedOperations(usersPathItem, ['put', 'delete'], '/users')).toThrow(
+        new Error(
+          'None of the requested methods (put, delete) are valid for path "/users". Available methods: get, post'
+        )
+      );
+    });
+
+    it('should throw Error if requested methods array is empty', () => {
+      // The calling handler should prevent this, but test the helper
+      expect(() => getValidatedOperations(usersPathItem, [], '/users')).toThrow(
+        new Error(
+          'None of the requested methods () are valid for path "/users". Available methods: get, post'
+        )
+      );
+    });
+
+    it('should throw Error if path item has no valid methods', () => {
+      expect(() => getValidatedOperations(itemsPathItem, ['get'], '/items')).toThrow(
+        new Error(
+          'None of the requested methods (get) are valid for path "/items". Available methods: '
+        )
+      );
+    });
+  });
+
+  // --- getValidatedComponentMap ---
+  describe('getValidatedComponentMap', () => {
+    it('should return the component map for a valid type', () => {
+      const schemasMap = getValidatedComponentMap(mockSpec, 'schemas');
+      expect(schemasMap).toBeDefined();
+      expect(schemasMap).toHaveProperty('User');
+      expect(schemasMap).toHaveProperty('Error');
+    });
+
+    it('should return the component map for another valid type', () => {
+      const responsesMap = getValidatedComponentMap(mockSpec, 'responses');
+      expect(responsesMap).toBeDefined();
+      expect(responsesMap).toHaveProperty('NotFound');
+    });
+
+    it('should throw Error if component type is not found', () => {
+      expect(() => getValidatedComponentMap(mockSpec, 'parameters')).toThrow(
+        new Error(
+          'Component type "parameters" not found in the specification. Available types: schemas, responses'
+        )
+      );
+    });
+
+    it('should throw Error if spec has no components section', () => {
+      expect(() => getValidatedComponentMap(mockSpecNoComponents, 'schemas')).toThrow(
+        new Error('Specification does not contain a components section.')
+      );
+    });
+  });
+
+  // --- getValidatedComponentDetails ---
+  describe('getValidatedComponentDetails', () => {
+    const schemasMap = mockSpec.components?.schemas as Record<string, OpenAPIV3.SchemaObject>;
+    const responsesMap = mockSpec.components?.responses as Record<string, OpenAPIV3.ResponseObject>;
+    const detailsMapSchemas = new Map(Object.entries(schemasMap));
+    const detailsMapResponses = new Map(Object.entries(responsesMap));
+
+    it('should return details for valid requested names', () => {
+      const validDetails = getValidatedComponentDetails(
+        detailsMapSchemas,
+        ['User', 'Error'],
+        'schemas'
+      );
+      expect(validDetails).toHaveLength(2);
+      expect(validDetails[0].name).toBe('User');
+      expect(validDetails[0].detail).toEqual(schemasMap['User']);
+      expect(validDetails[1].name).toBe('Error');
+      expect(validDetails[1].detail).toEqual(schemasMap['Error']);
+    });
+
+    it('should return details for a single valid requested name', () => {
+      const validDetails = getValidatedComponentDetails(detailsMapSchemas, ['User'], 'schemas');
+      expect(validDetails).toHaveLength(1);
+      expect(validDetails[0].name).toBe('User');
+      expect(validDetails[0].detail).toEqual(schemasMap['User']);
+    });
+
+    it('should return only details for valid names when some are invalid', () => {
+      const validDetails = getValidatedComponentDetails(
+        detailsMapSchemas,
+        ['User', 'NonExistent', 'Error'],
+        'schemas'
+      );
+      expect(validDetails).toHaveLength(2);
+      expect(validDetails[0].name).toBe('User');
+      expect(validDetails[1].name).toBe('Error');
+    });
+
+    it('should throw Error if no requested names are valid', () => {
+      expect(() =>
+        getValidatedComponentDetails(detailsMapSchemas, ['NonExistent1', 'NonExistent2'], 'schemas')
+      ).toThrow(
+        new Error(
+          // Expect sorted names: Error, User
+          'None of the requested names (NonExistent1, NonExistent2) are valid for component type "schemas". Available names: Error, User'
+        )
+      );
+    });
+
+    it('should throw Error if requested names array is empty', () => {
+      // The calling handler should prevent this, but test the helper
+      expect(() => getValidatedComponentDetails(detailsMapSchemas, [], 'schemas')).toThrow(
+        new Error(
+          // Expect sorted names: Error, User
+          'None of the requested names () are valid for component type "schemas". Available names: Error, User'
+        )
+      );
+    });
+
+    it('should work for other component types (responses)', () => {
+      const validDetails = getValidatedComponentDetails(
+        detailsMapResponses,
+        ['NotFound'],
+        'responses'
+      );
+      expect(validDetails).toHaveLength(1);
+      expect(validDetails[0].name).toBe('NotFound');
+      expect(validDetails[0].detail).toEqual(responsesMap['NotFound']);
+    });
+  });
+});