@servicetitan/journey 1.0.0

package/src/__tests__/fetch.test.ts

@@ -0,0 +1,264 @@
+/** @jest-environment jsdom */
+import { activeJourneyStep, reportBackendRequest, type JourneyStepRef } from '../core';
+import { instrumentFetch, type InstrumentFetchOptions } from '../integrations/fetch';
+import { requestKey } from '../integrations/request-key';
+
+jest.mock('../core', () => ({
+    ...jest.requireActual('../core'),
+    activeJourneyStep: jest.fn(),
+    reportBackendRequest: jest.fn(),
+}));
+jest.mock('../integrations/request-key');
+
+describe('[journey] instrumentFetch', () => {
+    const KEY = 'resolved-endpoint-key';
+    const step = { name: 'load' } as unknown as JourneyStepRef;
+
+    let target: { fetch: jest.Mock };
+    let originalFetch: jest.Mock;
+    let response: { status: number };
+    let input: RequestInfo | URL;
+    let init: RequestInit | undefined;
+    let options: InstrumentFetchOptions;
+    let now: number;
+
+    beforeEach(() => {
+        jest.clearAllMocks();
+
+        response = { status: 200 };
+        originalFetch = jest.fn().mockResolvedValue(response);
+        target = { fetch: originalFetch };
+
+        input = 'https://api.example.com/orders';
+        init = undefined;
+        options = { target };
+
+        jest.mocked(activeJourneyStep).mockReturnValue(step);
+        jest.mocked(requestKey).mockReturnValue(KEY);
+
+        // Deterministic clock: each globalThis.performance.now() advances by 100ms.
+        now = 1_000;
+        jest.spyOn(globalThis.performance, 'now').mockImplementation(() => (now += 100));
+    });
+
+    afterEach(() => {
+        jest.restoreAllMocks();
+    });
+
+    const subject = () => {
+        instrumentFetch(options);
+        return target.fetch(input, init);
+    };
+
+    test('replaces the target fetch', () => {
+        instrumentFetch(options);
+
+        expect(target.fetch).not.toBe(originalFetch);
+    });
+
+    test('is idempotent for the same target', async () => {
+        const first = target.fetch;
+        instrumentFetch(options);
+        const wrapped = target.fetch;
+        const restoreNoop = instrumentFetch(options);
+
+        expect(target.fetch).toBe(wrapped);
+        expect(target.fetch).not.toBe(first);
+
+        restoreNoop();
+        expect(target.fetch).toBe(wrapped);
+
+        await target.fetch(input, init);
+        expect(originalFetch).toHaveBeenCalledTimes(1);
+        expect(reportBackendRequest).toHaveBeenCalledTimes(1);
+    });
+
+    test('delegates to the original fetch with the same arguments', async () => {
+        init = { method: 'POST' };
+
+        await subject();
+
+        expect(originalFetch).toHaveBeenCalledWith(input, init);
+    });
+
+    test('returns the original response', async () => {
+        const result = await subject();
+
+        expect(result).toBe(response);
+    });
+
+    test('reports the finished request against the active step', async () => {
+        await subject();
+
+        expect(reportBackendRequest).toHaveBeenCalledWith(step, 200, 100, KEY);
+    });
+
+    describe('when no journey step is active', () => {
+        beforeEach(() => jest.mocked(activeJourneyStep).mockReturnValue(null));
+
+        test('does not report the request', async () => {
+            await subject();
+
+            expect(reportBackendRequest).not.toHaveBeenCalled();
+        });
+
+        test('still delegates to the original fetch', async () => {
+            await subject();
+
+            expect(originalFetch).toHaveBeenCalledWith(input, init);
+        });
+    });
+
+    describe('when the active step changes before the response settles', () => {
+        beforeEach(() => {
+            originalFetch.mockImplementation(() => {
+                // The step captured at call time must win over whatever is active later.
+                jest.mocked(activeJourneyStep).mockReturnValue({ name: 'other' } as JourneyStepRef);
+                return Promise.resolve(response);
+            });
+        });
+
+        test('reports against the step captured at call time', async () => {
+            await subject();
+
+            expect(reportBackendRequest).toHaveBeenCalledWith(step, 200, 100, KEY);
+        });
+    });
+
+    describe('when the fetch rejects', () => {
+        const error = new Error('network down');
+
+        beforeEach(() => originalFetch.mockRejectedValue(error));
+
+        test('re-throws the original error', async () => {
+            await expect(subject()).rejects.toBe(error);
+        });
+
+        test('reports the failure with an undefined status', async () => {
+            await subject().catch(() => {});
+
+            expect(reportBackendRequest).toHaveBeenCalledWith(step, undefined, 100, KEY);
+        });
+    });
+
+    describe('endpoint key resolution', () => {
+        const baseURL = 'https://api.example.com';
+
+        beforeEach(() => (options.baseURL = baseURL));
+
+        describe('with a string url', () => {
+            beforeEach(() => (input = 'https://api.example.com/orders'));
+
+            test('passes the string and baseURL to requestKey', async () => {
+                await subject();
+
+                expect(requestKey).toHaveBeenCalledWith(
+                    'https://api.example.com/orders',
+                    undefined,
+                    baseURL
+                );
+            });
+        });
+
+        describe('with a URL object', () => {
+            beforeEach(() => (input = new URL('https://api.example.com/orders')));
+
+            test('passes its href to requestKey', async () => {
+                await subject();
+
+                expect(requestKey).toHaveBeenCalledWith(
+                    'https://api.example.com/orders',
+                    undefined,
+                    baseURL
+                );
+            });
+        });
+
+        describe('with a Request object', () => {
+            let request: Request;
+
+            beforeEach(() => {
+                request = new Request('https://api.example.com/orders');
+                input = request;
+            });
+
+            test('passes its url to requestKey', async () => {
+                await subject();
+
+                expect(requestKey).toHaveBeenCalledWith(request.url, undefined, baseURL);
+            });
+        });
+
+        describe('with an unrecognized input', () => {
+            beforeEach(() => (input = { notAUrl: true } as unknown as RequestInfo));
+
+            test('passes undefined to requestKey', async () => {
+                await subject();
+
+                expect(requestKey).toHaveBeenCalledWith(undefined, undefined, baseURL);
+            });
+        });
+    });
+
+    describe('when init carries an explicit journeyStep', () => {
+        const explicit = { name: 'explicit' } as unknown as JourneyStepRef;
+
+        beforeEach(() => {
+            init = { journeyStep: explicit } as RequestInit;
+            jest.mocked(activeJourneyStep).mockReturnValue(step);
+        });
+
+        test('prefers the explicit step over ambient', async () => {
+            await subject();
+
+            expect(reportBackendRequest).toHaveBeenCalledWith(explicit, 200, 100, KEY);
+        });
+    });
+
+    describe('the returned restore function', () => {
+        test('puts the original fetch back', () => {
+            const restore = instrumentFetch(options);
+            restore();
+
+            expect(target.fetch).toBe(originalFetch);
+        });
+
+        test('allows re-instrumentation after restore', () => {
+            const restore = instrumentFetch(options);
+            restore();
+            instrumentFetch(options);
+
+            expect(target.fetch).not.toBe(originalFetch);
+        });
+
+        test('is a no-op when restore is called twice', () => {
+            const restore = instrumentFetch(options);
+            restore();
+            target.fetch = originalFetch;
+            restore();
+
+            expect(target.fetch).toBe(originalFetch);
+        });
+    });
+
+    describe('without an explicit target', () => {
+        let originalGlobalFetch: typeof globalThis.fetch;
+
+        beforeEach(() => {
+            originalGlobalFetch = globalThis.fetch;
+            options = {};
+        });
+
+        afterEach(() => {
+            globalThis.fetch = originalGlobalFetch;
+        });
+
+        test('wraps the global fetch', () => {
+            const restore = instrumentFetch(options);
+
+            expect(globalThis.fetch).not.toBe(originalGlobalFetch);
+
+            restore();
+        });
+    });
+});

package/src/__tests__/jquery.test.ts

@@ -0,0 +1,327 @@
+/** @jest-environment jsdom */
+import { useJourneyTestRuntime } from '../__mocks__/test-runtime';
+import { completeJourney, journeyStep, startJourney } from '../core';
+import { instrumentJquery } from '../integrations/jquery/instrument';
+
+const emitMock = jest.fn();
+
+function createJqueryMock() {
+    const prefilters: ((o: any, orig: any, xhr: any) => void)[] = [];
+    const completes: ((event: unknown, xhr: any, settings: any) => void)[] = [];
+
+    const $ = ((_selector: Document) => ({
+        ajaxComplete(handler: (event: unknown, xhr: any, settings: any) => void) {
+            completes.push(handler);
+        },
+    })) as any;
+
+    $.ajaxPrefilter = (handler: (o: any, orig: any, xhr: any) => void) => {
+        prefilters.push(handler);
+    };
+    $.__prefilters = prefilters;
+    $.__completes = completes;
+    return $;
+}
+
+function simulateAjax($: any, url: string, status: number, durationMs = 10) {
+    const xhr = { status };
+    const settings = { url };
+    const start = globalThis.performance.now();
+
+    for (const prefilter of $.__prefilters) {
+        prefilter(settings, settings, xhr);
+    }
+
+    (globalThis.performance.now as jest.Mock).mockReturnValue(start + durationMs);
+
+    for (const complete of $.__completes) {
+        complete({}, xhr, settings);
+    }
+}
+
+describe('[journey] instrumentJquery', () => {
+    useJourneyTestRuntime(emitMock);
+
+    beforeEach(() => {
+        jest.spyOn(globalThis.performance, 'now').mockReturnValue(1_000);
+    });
+
+    afterEach(() => {
+        jest.restoreAllMocks();
+    });
+
+    test('is idempotent for the same $ instance', () => {
+        const $ = createJqueryMock();
+        instrumentJquery($);
+        instrumentJquery($);
+
+        expect($.__prefilters).toHaveLength(1);
+        expect($.__completes).toHaveLength(1);
+    });
+
+    test('ignores ajax outside an active journey step', () => {
+        const $ = createJqueryMock();
+        instrumentJquery($);
+
+        startJourney({
+            name: 'jq-idle',
+            team: 'test',
+            group: 'test',
+            service: 'test',
+            timeoutMs: 0,
+            requestTimeoutMs: 50,
+        });
+
+        simulateAjax($, '/CallScreen/BookJob', 500);
+        completeJourney('jq-idle');
+
+        expect(emitMock).toHaveBeenCalledTimes(1);
+        expect(emitMock.mock.calls[0][0].journey.outcome).toBe('good');
+    });
+
+    test('marks journey bad on 5xx inside a journey step', async () => {
+        const $ = createJqueryMock();
+        instrumentJquery($);
+
+        startJourney({
+            name: 'jq-5xx',
+            team: 'test',
+            group: 'test',
+            service: 'test',
+            timeoutMs: 0,
+            requestTimeoutMs: 5_000,
+        });
+
+        await journeyStep('jq-5xx', 'book-job', () => {
+            simulateAjax($, '/CallScreen/BookJob', 500, 20);
+        });
+
+        expect(emitMock).toHaveBeenCalledTimes(1);
+        const event = emitMock.mock.calls[0][0].journey;
+        expect(event.outcome).toBe('bad');
+        expect(event.reason).toBe('request-error');
+    });
+
+    test('marks journey bad on slow request inside a journey step', async () => {
+        const $ = createJqueryMock();
+        instrumentJquery($);
+
+        startJourney({
+            name: 'jq-slow',
+            team: 'test',
+            group: 'test',
+            service: 'test',
+            timeoutMs: 0,
+            requestTimeoutMs: 50,
+        });
+
+        await journeyStep('jq-slow', 'book-job', () => {
+            simulateAjax($, '/CallScreen/BookJob', 200, 200);
+        });
+
+        expect(emitMock).toHaveBeenCalledTimes(1);
+        const event = emitMock.mock.calls[0][0].journey;
+        expect(event.outcome).toBe('bad');
+        expect(event.reason).toBe('request-latency');
+    });
+
+    test('treats status 0 as a network/request error', async () => {
+        const $ = createJqueryMock();
+        instrumentJquery($);
+
+        startJourney({
+            name: 'jq-network',
+            team: 'test',
+            group: 'test',
+            service: 'test',
+            timeoutMs: 0,
+            requestTimeoutMs: 5_000,
+        });
+
+        await journeyStep('jq-network', 'book-job', () => {
+            simulateAjax($, '/CallScreen/BookJob', 0, 10);
+        });
+
+        expect(emitMock).toHaveBeenCalledTimes(1);
+        expect(emitMock.mock.calls[0][0].journey.outcome).toBe('bad');
+        expect(emitMock.mock.calls[0][0].journey.reason).toBe('request-error');
+    });
+
+    test('does not mark bad on 4xx (user/validation)', async () => {
+        const $ = createJqueryMock();
+        instrumentJquery($);
+
+        startJourney({
+            name: 'jq-4xx',
+            team: 'test',
+            group: 'test',
+            service: 'test',
+            timeoutMs: 0,
+            requestTimeoutMs: 5_000,
+        });
+
+        await journeyStep('jq-4xx', 'book-job', () => {
+            simulateAjax($, '/CallScreen/BookJob', 400, 10);
+        });
+        completeJourney('jq-4xx');
+
+        expect(emitMock).toHaveBeenCalledTimes(1);
+        expect(emitMock.mock.calls[0][0].journey.outcome).toBe('good');
+    });
+
+    test('honors an explicit journeyStep already stamped on the XHR', async () => {
+        const $ = createJqueryMock();
+        instrumentJquery($);
+
+        startJourney({
+            name: 'jq-explicit',
+            team: 'test',
+            group: 'test',
+            service: 'test',
+            timeoutMs: 0,
+            requestTimeoutMs: 5_000,
+        });
+
+        await journeyStep('jq-explicit', 'book-job', step => {
+            const tagged = step.tag() as { journeyStep: unknown };
+            const xhr: {
+                status: number;
+                journeyStep: unknown;
+                journeyStart?: number;
+            } = { status: 500, journeyStep: tagged.journeyStep };
+            const settings = { url: '/CallScreen/BookJob' };
+            const start = globalThis.performance.now();
+            for (const prefilter of $.__prefilters) {
+                prefilter(settings, settings, xhr);
+            }
+            // Prefilter must not clear the explicit step; it should stamp a start time.
+            expect(xhr.journeyStep).toBe(tagged.journeyStep);
+            expect(xhr.journeyStart).toBeDefined();
+            (globalThis.performance.now as jest.Mock).mockReturnValue(start + 20);
+            for (const complete of $.__completes) {
+                complete({}, xhr, settings);
+            }
+        });
+
+        expect(emitMock).toHaveBeenCalledTimes(1);
+        expect(emitMock.mock.calls[0][0].journey.outcome).toBe('bad');
+        expect(emitMock.mock.calls[0][0].journey.reason).toBe('request-error');
+    });
+
+    test('falls back to performance.now when journeyStart is missing', async () => {
+        const $ = createJqueryMock();
+        instrumentJquery($);
+
+        startJourney({
+            name: 'jq-no-start',
+            team: 'test',
+            group: 'test',
+            service: 'test',
+            timeoutMs: 0,
+            requestTimeoutMs: 5_000,
+        });
+
+        await journeyStep('jq-no-start', 'book-job', step => {
+            const tagged = step.tag() as { journeyStep: unknown };
+            // Bypass prefilter stamping — only fire ajaxComplete with a step and no start.
+            const xhr = { status: 200, journeyStep: tagged.journeyStep };
+            for (const complete of $.__completes) {
+                complete({}, xhr, { url: '/ok' });
+            }
+        });
+        completeJourney('jq-no-start');
+
+        expect(emitMock).toHaveBeenCalledTimes(1);
+        expect(emitMock.mock.calls[0][0].journey.outcome).toBe('good');
+    });
+
+    test('honors step.tag() on ajax settings without deep-merge stack overflow', async () => {
+        const $ = createJqueryMock();
+        instrumentJquery($);
+
+        // Mimic jQuery.ajaxSetup: deep-merge plain objects only (class instances by ref).
+        function isPlainObject(obj: unknown): obj is Record<string, unknown> {
+            return (
+                !!obj && typeof obj === 'object' && Object.getPrototypeOf(obj) === Object.prototype
+            );
+        }
+        function deepExtend(target: Record<string, unknown>, ...sources: unknown[]) {
+            for (const source of sources) {
+                if (!source || typeof source !== 'object') {
+                    continue;
+                }
+                for (const key of Object.keys(source as object)) {
+                    // Block prototype-polluting keys (CodeQL js/prototype-pollution-utility).
+                    if (key === '__proto__' || key === 'constructor' || key === 'prototype') {
+                        continue;
+                    }
+                    const copy = (source as Record<string, unknown>)[key];
+                    if (isPlainObject(copy)) {
+                        const dest = isPlainObject(target[key])
+                            ? (target[key] as Record<string, unknown>)
+                            : {};
+                        target[key] = deepExtend(dest, copy);
+                    } else {
+                        target[key] = copy;
+                    }
+                }
+            }
+            return target;
+        }
+
+        startJourney({
+            name: 'jq-settings-tag',
+            team: 'test',
+            group: 'test',
+            service: 'test',
+            timeoutMs: 0,
+            requestTimeoutMs: 5_000,
+        });
+
+        await journeyStep('jq-settings-tag', 'book-job', step => {
+            const tagged = step.tag() as { journeyStep: unknown };
+            expect(() => deepExtend({}, tagged)).not.toThrow();
+            const settings = deepExtend({ url: '/CallScreen/BookJob' }, tagged);
+            const xhr: { status: number; journeyStep?: unknown; journeyStart?: number } = {
+                status: 500,
+            };
+            const start = globalThis.performance.now();
+            for (const prefilter of $.__prefilters) {
+                prefilter(settings, settings, xhr);
+            }
+            expect(xhr.journeyStep).toBe(tagged.journeyStep);
+            (globalThis.performance.now as jest.Mock).mockReturnValue(start + 20);
+            for (const complete of $.__completes) {
+                complete({}, xhr, settings);
+            }
+        });
+
+        expect(emitMock).toHaveBeenCalledTimes(1);
+        expect(emitMock.mock.calls[0][0].journey.outcome).toBe('bad');
+        expect(emitMock.mock.calls[0][0].journey.reason).toBe('request-error');
+    });
+
+    test('keys cross-origin ajax urls as host/path', async () => {
+        const $ = createJqueryMock();
+        instrumentJquery($);
+
+        startJourney({
+            name: 'jq-cross',
+            team: 'test',
+            group: 'test',
+            service: 'test',
+            timeoutMs: 0,
+            requestTimeoutMs: 5_000,
+            endpoints: [{ match: 'pdf.vendor.com/render', ignore: true }],
+        });
+
+        await journeyStep('jq-cross', 'book-job', () => {
+            simulateAjax($, 'https://pdf.vendor.com/render', 500, 20);
+        });
+        completeJourney('jq-cross');
+
+        // Ignored endpoint — 5xx must not close the journey as bad.
+        expect(emitMock).toHaveBeenCalledTimes(1);
+        expect(emitMock.mock.calls[0][0].journey.outcome).toBe('good');
+    });
+});