@vida-global/core 2.0.11 → 2.1.1

package/test/server/controllerMixins/renderer.test.js

@@ -0,0 +1,734 @@
+const { FooController }        = require('../helpers/controllers/fooController');
+const   TestHelpers            = require('@vida-global/test-helpers');
+const {
+    NoActiveStreamError,
+    StreamInProgressError,
+}                              = require('../../../lib/server/serverController');
+
+
+describe('VidaServerController', () => {
+    describe('Rendering', () => {
+        let controller;
+        let response;
+        beforeEach(() => {
+            response          = {json: jest.fn(), statusCode: 200};
+            controller        = new FooController({}, response);
+            controller.render = jest.fn();
+        });
+
+        describe('#renderErrors', () => {
+            it ('returns a 400 response', async () => {
+                await controller.renderErrors();
+                expect(response.statusCode).toBe(400);
+            })
+
+            it ('includes a blank message and blank fields by default', async () => {
+                await controller.renderErrors();
+                expect(controller.render).toHaveBeenCalledTimes(1);
+                expect(controller.render).toHaveBeenCalledWith({errors: {message: null, fields: {}}});
+            })
+
+            it ('includes a provided message', async () => {
+                const msg = TestHelpers.Faker.Text.randomString();
+                await controller.renderErrors(msg);
+                expect(controller.render).toHaveBeenCalledTimes(1);
+                expect(controller.render).toHaveBeenCalledWith({errors: {message: msg, fields: {}}});
+            });
+
+            it ('includes provided field data', async () => {
+                const field1 = TestHelpers.Faker.Text.randomString();
+                const msg1   = TestHelpers.Faker.Text.randomString();
+                const msg2   = TestHelpers.Faker.Text.randomString();
+                await controller.renderErrors(null, {[field1]: [msg1, msg2]});
+                expect(controller.render).toHaveBeenCalledTimes(1);
+                expect(controller.render).toHaveBeenCalledWith({errors: {message: null, fields: {[field1]: [msg1, msg2]}}});
+            });
+
+            it ('includes provided message field data', async () => {
+                const field1 = TestHelpers.Faker.Text.randomString();
+                const msg1   = TestHelpers.Faker.Text.randomString();
+                const msg2   = TestHelpers.Faker.Text.randomString();
+                const msg3   = TestHelpers.Faker.Text.randomString();
+                await controller.renderErrors(msg1, {[field1]: [msg2, msg3]});
+                expect(controller.render).toHaveBeenCalledTimes(1);
+                expect(controller.render).toHaveBeenCalledWith({errors: {message: msg1, fields: {[field1]: [msg2, msg3]}}});
+            });
+
+            it ('uses the first parameter as fields if it is an object', async () => {
+                const field1 = TestHelpers.Faker.Text.randomString();
+                const msg1   = TestHelpers.Faker.Text.randomString();
+                const msg2   = TestHelpers.Faker.Text.randomString();
+                await controller.renderErrors({[field1]: [msg1, msg2]});
+                expect(controller.render).toHaveBeenCalledTimes(1);
+                expect(controller.render).toHaveBeenCalledWith({errors: {message: null, fields: {[field1]: [msg1, msg2]}}});
+            });
+
+            it ('converts single field error messages to arrays', async () => {
+                const field1 = TestHelpers.Faker.Text.randomString();
+                const msg1   = TestHelpers.Faker.Text.randomString();
+                await controller.renderErrors({[field1]: msg1});
+                expect(controller.render).toHaveBeenCalledTimes(1);
+                expect(controller.render).toHaveBeenCalledWith({errors: {message: null, fields: {[field1]: [msg1]}}});
+            });
+        });
+
+
+        const successHandlers = [
+            ['renderCreationSuccessful', 201],
+            ['renderAccepted',           202],
+            ['renderNoConent',           204],
+            ['renderMovedPermanently',   301],
+            ['renderFound',              302],
+            ['renderNotModified',        304],
+            ['renderTemporaryRedirect',  307],
+            ['renderPermanentRedirect',  308],
+        ]
+        describe.each(successHandlers)('#%s', (handlerName, statusCode) => {
+            it (`returns a ${statusCode} response`, async () => {
+                await (controller[handlerName]());
+                expect(response.statusCode).toBe(statusCode);
+            })
+
+            it ('includes the provided body', async () => {
+                const key   = TestHelpers.Faker.Text.randomString();
+                const value = TestHelpers.Faker.Text.randomString();
+                const body  = {[key]: value};
+                await (controller[handlerName](body));
+
+                expect(controller.render).toHaveBeenCalledTimes(1);
+                expect(controller.render).toHaveBeenCalledWith(body);
+            });
+        });
+
+
+        const errorHandlers = [
+            ['renderUnauthorized',         401],
+            ['renderPaymentRequired',      402],
+            ['renderForbidden',            403],
+            ['renderNotFound',             404],
+            ['renderMethodNotAllowed',     405],
+            ['renderRequestTimeout',       408],
+            ['renderConflict',             409],
+            ['renderGone',                 410],
+            ['renderContentTooLarge',      413],
+            ['renderUnsupportedMediaType', 415],
+            ['renderUnprocessableContent', 422],
+            ['renderLocked',               423],
+            ['renderTooManyRequests',      429],
+            ['renderServerError',          500],
+            ['renderNotImplemented',       501],
+            ['renderBadGateway',           502],
+            ['renderServiceUnavailable',   503],
+            ['renderGatewayTimeout',       504],
+        ]
+
+        describe.each(errorHandlers)('#%s', (handlerName, statusCode) => {
+            it (`returns a ${statusCode} response`, async () => {
+                await (controller[handlerName]());
+                expect(response.statusCode).toBe(statusCode);
+            })
+
+            it ('includes a blank message by default', async () => {
+                await controller[handlerName]();
+                expect(controller.render).toHaveBeenCalledTimes(1);
+                expect(controller.render).toHaveBeenCalledWith({errors: {message: null}});
+            })
+
+            it ('includes a provided message', async () => {
+                const msg = TestHelpers.Faker.Text.randomString();
+                await controller[handlerName](msg);
+                expect(controller.render).toHaveBeenCalledTimes(1);
+                expect(controller.render).toHaveBeenCalledWith({errors: {message: msg}});
+            });
+
+            it ('includes a provided body and message', async () => {
+                const key      = TestHelpers.Faker.Text.randomString();
+                const val      = TestHelpers.Faker.Text.randomString();
+                const body     = {[key]: val};
+                const msg      = TestHelpers.Faker.Text.randomString();
+                const expected = {...body, errors: {message: msg}};
+                await controller[handlerName](msg, body);
+                expect(controller.render).toHaveBeenCalledTimes(1);
+                expect(controller.render).toHaveBeenCalledWith(expected);
+            });
+        });
+    });
+
+
+    describe('#render', () => {
+        let response;
+        let controller;
+        beforeEach(() => {
+            response   = {json: jest.fn(), send: jest.fn(), setHeader: jest.fn(), statusCode: 200};
+            controller = new FooController({}, response);
+        });
+
+        it ('calls response.send (not response.json) when the body is a string', async () => {
+            const body = TestHelpers.Faker.Text.randomString();
+            await controller.render(body);
+
+            expect(response.send).toHaveBeenCalledTimes(1);
+            expect(response.send).toHaveBeenCalledWith(body);
+            expect(response.json).not.toHaveBeenCalled();
+        });
+
+        it ('marks the controller as rendered after a string render', async () => {
+            await controller.render('hello');
+            expect(controller.rendered).toBe(true);
+        });
+
+        it ('is a no-op when the controller has already been rendered', async () => {
+            controller.markRendered();
+            await controller.render('hello');
+            expect(response.send).not.toHaveBeenCalled();
+            expect(response.json).not.toHaveBeenCalled();
+        });
+
+        it ('is a no-op when the controller is streaming', async () => {
+            controller._isStreaming = true;
+            await controller.render('hello');
+            await controller.render({foo: 'bar'});
+
+            expect(response.send).not.toHaveBeenCalled();
+            expect(response.json).not.toHaveBeenCalled();
+        });
+
+        it ('does not mark the controller as rendered when streaming', async () => {
+            controller._isStreaming = true;
+            await controller.render('hello');
+            expect(controller.rendered).toBe(false);
+        });
+    });
+
+
+    describe('#_serializeResponseBody', () => {
+        let controller;
+        beforeEach(() => {
+            controller = new FooController({}, {});
+        });
+
+        it ('returns null when the body is undefined', async () => {
+            expect(await controller._serializeResponseBody(undefined, {})).toBe(null);
+        });
+
+        it ('returns null when the body is null', async () => {
+            expect(await controller._serializeResponseBody(null, {})).toBe(null);
+        });
+
+        it ('returns primitives unchanged', async () => {
+            expect(await controller._serializeResponseBody('hello', {})).toBe('hello');
+            expect(await controller._serializeResponseBody(42,      {})).toBe(42);
+            expect(await controller._serializeResponseBody(true,    {})).toBe(true);
+        });
+
+        it ('returns Date instances as their epoch ms via getTime', async () => {
+            const date = new Date('2020-01-02T03:04:05Z');
+            expect(await controller._serializeResponseBody(date, {})).toBe(date.getTime());
+        });
+
+        it ('recursively processes Date values inside objects', async () => {
+            const date = new Date('2021-02-03T00:00:00Z');
+            const result = await controller._serializeResponseBody({createdAt: date, name: 'foo'}, {});
+            expect(result).toEqual({createdAt: date.getTime(), name: 'foo'});
+        });
+
+        it ('recursively processes arrays', async () => {
+            const date = new Date('2022-03-04T00:00:00Z');
+            const result = await controller._serializeResponseBody([1, date, {ts: date}], {});
+            expect(result).toEqual([1, date.getTime(), {ts: date.getTime()}]);
+        });
+
+        it ('invokes toApiResponse on objects that define it and recurses on the result', async () => {
+            const date     = new Date('2023-04-05T00:00:00Z');
+            const apiModel = {
+                async toApiResponse() { return {id: 1, createdAt: date}; }
+            };
+            const result = await controller._serializeResponseBody(apiModel, {});
+            expect(result).toEqual({id: 1, createdAt: date.getTime()});
+        });
+
+        it ('passes the options argument through to toApiResponse', async () => {
+            const options    = {includeTitle: true, extra: 'flag'};
+            const toApi      = jest.fn().mockResolvedValue({});
+            const apiModel   = {toApiResponse: toApi};
+
+            await controller._serializeResponseBody(apiModel, options);
+            expect(toApi).toHaveBeenCalledWith(options);
+        });
+
+        it ('recurses through arrays of objects with toApiResponse', async () => {
+            const apiModels = [
+                {toApiResponse: async () => ({id: 'a'})},
+                {toApiResponse: async () => ({id: 'b'})},
+            ];
+            const result = await controller._serializeResponseBody(apiModels, {});
+            expect(result).toEqual([{id: 'a'}, {id: 'b'}]);
+        });
+    });
+
+
+    describe('#requestedFormat', () => {
+        it ('returns "xml" when the _format param is xml', () => {
+            const controller = new FooController({query: {_format: 'xml'}}, {});
+            expect(controller.requestedFormat).toBe('xml');
+        });
+
+        it ('returns "json" when the _format param is json', () => {
+            const controller = new FooController({query: {_format: 'json'}}, {});
+            expect(controller.requestedFormat).toBe('json');
+        });
+
+        it ('returns "xml" when the Accept header requests xml', () => {
+            const controller = new FooController({headers: {accept: 'application/xml'}}, {});
+            expect(controller.requestedFormat).toBe('xml');
+        });
+
+        it ('lets the _format param override a conflicting Accept header', () => {
+            const controller = new FooController({query: {_format: 'json'}, headers: {accept: 'application/xml'}}, {});
+            expect(controller.requestedFormat).toBe('json');
+        });
+
+        it ('defaults to json when neither the param nor the header indicate a format', () => {
+            const controller = new FooController({}, {});
+            expect(controller.requestedFormat).toBe('json');
+        });
+
+        it ('ignores an unrecognized _format and falls back to the Accept header', () => {
+            const controller = new FooController({query: {_format: 'yaml'}, headers: {accept: 'application/xml'}}, {});
+            expect(controller.requestedFormat).toBe('xml');
+        });
+    });
+
+
+    describe('#isXMLRequest', () => {
+        it ('is true when the requested format is xml', () => {
+            const controller = new FooController({query: {_format: 'xml'}}, {});
+            expect(controller.isXMLRequest).toBe(true);
+        });
+
+        it ('is false when the requested format is json', () => {
+            const controller = new FooController({}, {});
+            expect(controller.isXMLRequest).toBe(false);
+        });
+    });
+
+
+    describe('#isJSONRequest', () => {
+        it ('is true when the requested format is json', () => {
+            const controller = new FooController({}, {});
+            expect(controller.isJSONRequest).toBe(true);
+        });
+
+        it ('is false when the requested format is xml', () => {
+            const controller = new FooController({query: {_format: 'xml'}}, {});
+            expect(controller.isJSONRequest).toBe(false);
+        });
+    });
+
+
+    describe('#render format dispatch', () => {
+        let response;
+        beforeEach(() => {
+            response = {json: jest.fn(), send: jest.fn(), setHeader: jest.fn(), statusCode: 200};
+        });
+
+        it ('renders JSON via response.json for a JSON request', async () => {
+            const controller = new FooController({}, response);
+            await controller.render({foo: 'bar'});
+            expect(response.json).toHaveBeenCalledTimes(1);
+            expect(response.send).not.toHaveBeenCalled();
+        });
+
+        it ('sets the JSON content-type for a JSON request', async () => {
+            const controller = new FooController({}, response);
+            await controller.render({foo: 'bar'});
+            expect(response.setHeader).toHaveBeenCalledWith('content-type', 'application/json; charset=utf-8');
+        });
+
+        it ('renders XML via response.send for an XML request', async () => {
+            const controller = new FooController({query: {_format: 'xml'}}, response);
+            await controller.render({foo: 'bar'});
+            expect(response.send).toHaveBeenCalledTimes(1);
+            expect(response.json).not.toHaveBeenCalled();
+        });
+
+        it ('sets the XML content-type for an XML request', async () => {
+            const controller = new FooController({query: {_format: 'xml'}}, response);
+            await controller.render({foo: 'bar'});
+            expect(response.setHeader).toHaveBeenCalledWith('content-type', 'application/xml; charset=utf-8');
+        });
+
+        it ('serializes the body under a <response> root for an XML request', async () => {
+            const controller = new FooController({query: {_format: 'xml'}}, response);
+            await controller.render({foo: 'bar'});
+            const sent = response.send.mock.calls[0][0];
+            expect(sent).toContain('<response>');
+            expect(sent).toContain('<data><foo>bar</foo></data>');
+            expect(sent).toContain('<status>ok</status>');
+        });
+
+        it ('renders array items as separate elements instead of concatenated text', async () => {
+            const controller = new FooController({query: {_format: 'xml'}}, response);
+            await controller.render({tags: ['one', 'two']});
+            const sent = response.send.mock.calls[0][0];
+            expect(sent).toContain('<item>one</item><item>two</item>');
+        });
+
+        it ('sanitizes invalid XML element names so dynamic keys do not throw', async () => {
+            const controller = new FooController({query: {_format: 'xml'}}, response);
+            await controller.render({'123': 'x', 'first name': 'y'});
+            const sent = response.send.mock.calls[0][0];
+            expect(sent).toContain('<_123>x</_123>');
+            expect(sent).toContain('<first_name>y</first_name>');
+        });
+    });
+
+
+    describe('#_serializeArrayForResponseBody', () => {
+        class FakeRecord {
+            constructor(id) { this.id = id; }
+            get apiXMLTagName() { return 'FakeRecord'; }
+        }
+
+        it ('returns a plain array for a JSON request', async () => {
+            const controller = new FooController({}, {});
+            const result     = await controller._serializeArrayForResponseBody([new FakeRecord(1), new FakeRecord(2)], {});
+            expect(result).toEqual([{id: 1}, {id: 2}]);
+        });
+
+        it ('wraps records in apiXMLTagName elements under "#" for an XML request', async () => {
+            const controller = new FooController({query: {_format: 'xml'}}, {});
+            const result     = await controller._serializeArrayForResponseBody([new FakeRecord(1), new FakeRecord(2)], {});
+            expect(result).toEqual({'#': [{FakeRecord: {id: 1}}, {FakeRecord: {id: 2}}]});
+        });
+
+        it ('wraps primitive elements in generic <item> tags for an XML request', async () => {
+            const controller = new FooController({query: {_format: 'xml'}}, {});
+            const result     = await controller._serializeArrayForResponseBody(['one', 'two'], {});
+            expect(result).toEqual({'#': [{item: 'one'}, {item: 'two'}]});
+        });
+
+        it ('wraps null elements in generic <item> tags for an XML request', async () => {
+            const controller = new FooController({query: {_format: 'xml'}}, {});
+            const result     = await controller._serializeArrayForResponseBody([null, new FakeRecord(1)], {});
+            expect(result).toEqual({'#': [{item: null}, {FakeRecord: {id: 1}}]});
+        });
+    });
+
+
+    describe('#_toXMLElementName', () => {
+        let controller;
+        beforeEach(() => {
+            controller = new FooController({}, {});
+        });
+
+        it ('leaves a valid XML name unchanged', () => {
+            expect(controller._toXMLElementName('firstName')).toBe('firstName');
+        });
+
+        it ('prefixes an underscore when the key starts with a digit', () => {
+            expect(controller._toXMLElementName('123')).toBe('_123');
+        });
+
+        it ('replaces spaces and other invalid characters with underscores', () => {
+            expect(controller._toXMLElementName('first name')).toBe('first_name');
+            expect(controller._toXMLElementName('a:b')).toBe('a_b');
+        });
+    });
+
+
+    describe('#statusText', () => {
+        const cases = [
+            [200, 'ok'],
+            [201, 'created'],
+            [202, 'accepted'],
+            [204, 'no content'],
+            [301, 'moved permanently'],
+            [302, 'found'],
+            [304, 'not modified'],
+            [307, 'temporary redirect'],
+            [308, 'permanent redirect'],
+            [400, 'bad request'],
+            [401, 'unauthorized'],
+            [402, 'payment required'],
+            [403, 'forbidden'],
+            [404, 'not found'],
+            [405, 'method not allowed'],
+            [408, 'request timeout'],
+            [409, 'conflict'],
+            [410, 'gone'],
+            [413, 'content too large'],
+            [415, 'unsupported media type'],
+            [422, 'unprocessable content'],
+            [423, 'locked'],
+            [429, 'too many requests'],
+            [500, 'server error'],
+            [501, 'not implemented'],
+            [502, 'bad gateway'],
+            [503, 'service unavailable'],
+            [504, 'gateway timeout'],
+        ];
+
+        it.each(cases)('returns "%s" text for status %s', (statusCode, expected) => {
+            const controller = new FooController({}, { statusCode });
+            expect(controller.statusText).toEqual(expected);
+        });
+
+        it ('returns undefined for an unmapped status code', () => {
+            const controller = new FooController({}, { statusCode: 418 });
+            expect(controller.statusText).toBeUndefined();
+        });
+    });
+
+
+    describe('#streamSseResponse', () => {
+        let controller;
+        let response;
+        let request;
+        let setHeaderSpy;
+
+        beforeEach(() => {
+            request          = { on: jest.fn(), off: jest.fn() };
+            response         = {
+                setHeader:     jest.fn(),
+                flushHeaders:  jest.fn(),
+                write:         jest.fn(),
+                end:           jest.fn(),
+                writableEnded: false
+            };
+            controller       = new FooController(request, response);
+            setHeaderSpy     = response.setHeader;
+        });
+
+        it ('sets SSE headers, flushes them, and marks rendered before invoking handler', async () => {
+            const handler = jest.fn(async function () {
+                expect(this).toBe(controller);
+                expect(controller.rendered).toBe(true);
+                expect(setHeaderSpy).toHaveBeenCalledWith('Content-Type',      'text/event-stream; charset=utf-8');
+                expect(setHeaderSpy).toHaveBeenCalledWith('Cache-Control',     'no-cache');
+                expect(setHeaderSpy).toHaveBeenCalledWith('Connection',        'keep-alive');
+                expect(setHeaderSpy).toHaveBeenCalledWith('X-Accel-Buffering', 'no');
+                expect(response.flushHeaders).toHaveBeenCalledTimes(1);
+                expect(controller.statusCode).toBe(200);
+            });
+            await controller.streamSseResponse(handler, jest.fn());
+            expect(handler).toHaveBeenCalledTimes(1);
+        });
+
+        it ('writes [DONE] and ends the response in the finally block', async () => {
+            await controller.streamSseResponse(jest.fn(), jest.fn());
+            expect(response.write).toHaveBeenLastCalledWith('data: [DONE]\n\n');
+            expect(response.end).toHaveBeenCalledTimes(1);
+        });
+
+        it ('throws StreamInProgressError when called while already streaming', async () => {
+            await controller.streamSseResponse(async () => {
+                await expect(controller.streamSseResponse(jest.fn(), jest.fn()))
+                    .rejects.toBeInstanceOf(StreamInProgressError);
+            }, jest.fn());
+        });
+
+        it ('invokes errorHandler and rethrows when handler throws', async () => {
+            const err          = new Error('boom');
+            const handler      = jest.fn(async () => { throw err; });
+            const errorHandler = jest.fn();
+            await expect(controller.streamSseResponse(handler, errorHandler)).rejects.toThrow('boom');
+            expect(errorHandler).toHaveBeenCalledWith(err);
+        });
+
+        it ('still ends the response when handler throws', async () => {
+            const errorHandler = jest.fn();
+            await expect(controller.streamSseResponse(
+                async () => { throw new Error('boom'); },
+                errorHandler
+            )).rejects.toThrow();
+            expect(response.end).toHaveBeenCalledTimes(1);
+        });
+
+        it ('wires close listener to abortController when one is provided', async () => {
+            const abortController = { abort: jest.fn() };
+            await controller.streamSseResponse(jest.fn(), jest.fn(), abortController);
+            expect(request.on).toHaveBeenCalledWith('close', expect.any(Function));
+            expect(request.off).toHaveBeenCalledWith('close', expect.any(Function));
+            // The handler registered on 'close' should call abort.
+            const closeHandler = request.on.mock.calls.find(c => c[0] === 'close')[1];
+            closeHandler();
+            expect(abortController.abort).toHaveBeenCalledTimes(1);
+        });
+
+        it ('does not register a close listener when no abortController is provided', async () => {
+            await controller.streamSseResponse(jest.fn(), jest.fn());
+            expect(request.on).not.toHaveBeenCalled();
+            expect(request.off).not.toHaveBeenCalled();
+        });
+
+        it ('resets streaming state after completion so a new stream can start', async () => {
+            await controller.streamSseResponse(jest.fn(), jest.fn());
+            // Second call should not throw StreamInProgressError.
+            await expect(controller.streamSseResponse(jest.fn(), jest.fn())).resolves.toBeUndefined();
+        });
+    });
+
+
+    describe('#writeStreamEvent', () => {
+        let controller;
+        let response;
+
+        beforeEach(() => {
+            response   = {
+                setHeader:     jest.fn(),
+                flushHeaders:  jest.fn(),
+                write:         jest.fn(),
+                end:           jest.fn(),
+                writableEnded: false
+            };
+            controller = new FooController({ on: jest.fn(), off: jest.fn() }, response);
+        });
+
+        it ('throws NoActiveStreamError when called outside a stream', () => {
+            expect(() => controller.writeStreamEvent('msg', 'hello'))
+                .toThrow(NoActiveStreamError);
+        });
+
+        it ('writes both event and data lines when an event name is provided', async () => {
+            await controller.streamSseResponse(async () => {
+                response.write.mockClear();
+                controller.writeStreamEvent('progress', 'halfway');
+                expect(response.write).toHaveBeenCalledTimes(1);
+                expect(response.write).toHaveBeenCalledWith('event: progress\ndata: halfway\n\n');
+            }, jest.fn());
+        });
+
+        it ('writes only the data line when no event name is provided', async () => {
+            await controller.streamSseResponse(async () => {
+                response.write.mockClear();
+                controller.writeStreamEvent(null, 'plain');
+                expect(response.write).toHaveBeenCalledTimes(1);
+                expect(response.write).toHaveBeenCalledWith('data: plain\n\n');
+            }, jest.fn());
+        });
+
+        it ('is a no-op when the response is already ended', async () => {
+            await controller.streamSseResponse(async () => {
+                response.writableEnded = true;
+                response.write.mockClear();
+                controller.writeStreamEvent(null, 'ignored');
+                expect(response.write).not.toHaveBeenCalled();
+            }, jest.fn());
+        });
+
+        it ('is a no-op when the abort signal is aborted', async () => {
+            const abortController = { abort: jest.fn(), signal: { aborted: false } };
+            await controller.streamSseResponse(async () => {
+                abortController.signal.aborted = true;
+                response.write.mockClear();
+                controller.writeStreamEvent(null, 'ignored');
+                expect(response.write).not.toHaveBeenCalled();
+            }, jest.fn(), abortController);
+        });
+    });
+
+
+    describe('#renderFile', () => {
+        let request;
+        let response;
+        let controller;
+
+
+        beforeEach(() => {
+            request    = {};
+            response   = {
+                setHeader: jest.fn(),
+                sendFile:  jest.fn((path, options, cb) => cb()),
+            };
+            controller = new FooController(request, response);
+        });
+
+
+        it ('sets Content-Type from the explicit option when provided', async () => {
+            await controller.renderFile('/var/www/foo.bin', { contentType: 'application/x-custom' });
+            expect(response.setHeader).toHaveBeenCalledWith('Content-Type', 'application/x-custom');
+        });
+
+
+        it.each([
+            ['/a/b.html',  'text/html; charset=utf-8'],
+            ['/a/b.htm',   'text/html; charset=utf-8'],
+            ['/a/b.css',   'text/css; charset=utf-8'],
+            ['/a/b.js',    'application/javascript; charset=utf-8'],
+            ['/a/b.mjs',   'application/javascript; charset=utf-8'],
+            ['/a/b.json',  'application/json; charset=utf-8'],
+            ['/a/b.txt',   'text/plain; charset=utf-8'],
+            ['/a/b.png',   'image/png'],
+            ['/a/b.jpg',   'image/jpeg'],
+            ['/a/b.jpeg',  'image/jpeg'],
+            ['/a/b.gif',   'image/gif'],
+            ['/a/b.svg',   'image/svg+xml'],
+            ['/a/b.ico',   'image/x-icon'],
+            ['/a/b.webp',  'image/webp'],
+            ['/a/b.woff',  'font/woff'],
+            ['/a/b.woff2', 'font/woff2'],
+            ['/a/b.ttf',   'font/ttf'],
+            ['/a/b.otf',   'font/otf'],
+            ['/a/b.JPG',   'image/jpeg'],
+        ])('guesses Content-Type for %s', async (filePath, expected) => {
+            await controller.renderFile(filePath);
+            expect(response.setHeader).toHaveBeenCalledWith('Content-Type', expected);
+        });
+
+
+        it ('falls back to application/octet-stream for unknown extensions', async () => {
+            await controller.renderFile('/var/www/foo.xyz');
+            expect(response.setHeader).toHaveBeenCalledWith('Content-Type', 'application/octet-stream');
+        });
+
+
+        it ('falls back to application/octet-stream when there is no extension', async () => {
+            await controller.renderFile('/var/www/foo');
+            expect(response.setHeader).toHaveBeenCalledWith('Content-Type', 'application/octet-stream');
+        });
+
+
+        it ('sets Cache-Control when provided', async () => {
+            await controller.renderFile('/var/www/foo.html', { cacheControl: 'no-store' });
+            expect(response.setHeader).toHaveBeenCalledWith('Cache-Control', 'no-store');
+        });
+
+
+        it ('does not set Cache-Control when omitted', async () => {
+            await controller.renderFile('/var/www/foo.html');
+            const cacheCalls = response.setHeader.mock.calls.filter(([name]) => name === 'Cache-Control');
+            expect(cacheCalls).toHaveLength(0);
+        });
+
+
+        it ('passes maxAge to res.sendFile', async () => {
+            await controller.renderFile('/var/www/foo.html', { maxAge: 300000 });
+            expect(response.sendFile).toHaveBeenCalledWith('/var/www/foo.html', { maxAge: 300000 }, expect.any(Function));
+        });
+
+
+        it ('marks the controller as rendered', async () => {
+            expect(controller.rendered).toBe(false);
+            await controller.renderFile('/var/www/foo.html');
+            expect(controller.rendered).toBe(true);
+        });
+
+
+        it ('throws when filePath is empty', () => {
+            expect(() => controller.renderFile('')).toThrow('renderFile requires a filePath');
+        });
+
+
+        it ('throws when filePath is null', () => {
+            expect(() => controller.renderFile(null)).toThrow('renderFile requires a filePath');
+        });
+
+
+        it ('rejects the returned promise when sendFile errors', async () => {
+            const sendError = new Error('disk read failed');
+            response.sendFile = jest.fn((path, options, cb) => cb(sendError));
+            await expect(controller.renderFile('/var/www/foo.html')).rejects.toBe(sendError);
+        });
+    });
+});