@servicetitan/journey 1.0.0

package/src/__tests__/axios.test.ts

@@ -0,0 +1,365 @@
+/** @jest-environment jsdom */
+import { useJourneyTestRuntime } from '../__mocks__/test-runtime';
+import { completeJourney, JourneyStepTag, journeyStep, startJourney } from '../core';
+import { instrumentAxios, type AxiosLikeInstance } from '../integrations/axios';
+
+const emitMock = jest.fn();
+
+type RequestHandler = (config: any) => any;
+type ResponseOk = (response: any) => any;
+type ResponseErr = (error: any) => any;
+
+function createAxiosMock(): AxiosLikeInstance & {
+    requestHandlers: RequestHandler[];
+    responseOkHandlers: ResponseOk[];
+    responseErrHandlers: ResponseErr[];
+} {
+    const request: RequestHandler[] = [];
+    const responseOk: ResponseOk[] = [];
+    const responseErr: ResponseErr[] = [];
+
+    return {
+        defaults: { baseURL: 'https://app.example.com' },
+        interceptors: {
+            request: {
+                use(onFulfilled) {
+                    request.push(onFulfilled);
+                    return 0;
+                },
+            },
+            response: {
+                use(onFulfilled, onRejected) {
+                    responseOk.push(onFulfilled);
+                    if (onRejected) {
+                        responseErr.push(onRejected);
+                    }
+                    return 0;
+                },
+            },
+        },
+        requestHandlers: request,
+        responseOkHandlers: responseOk,
+        responseErrHandlers: responseErr,
+    };
+}
+
+describe('[journey] instrumentAxios', () => {
+    const def = {
+        name: 'axios-journey',
+        team: 'test',
+        group: 'test',
+        service: 'test',
+        timeoutMs: 0,
+        requestTimeoutMs: 5_000,
+    };
+
+    useJourneyTestRuntime(emitMock);
+
+    beforeEach(() => {
+        jest.spyOn(globalThis.performance, 'now').mockReturnValue(1_000);
+    });
+
+    afterEach(() => {
+        jest.restoreAllMocks();
+    });
+
+    test('is idempotent for the same axios instance', () => {
+        const axios = createAxiosMock();
+        instrumentAxios(axios);
+        instrumentAxios(axios);
+
+        expect(axios.requestHandlers).toHaveLength(1);
+        expect(axios.responseOkHandlers).toHaveLength(1);
+        expect(axios.responseErrHandlers).toHaveLength(1);
+    });
+
+    test('reports a successful response against the ambient step', async () => {
+        const axios = createAxiosMock();
+        instrumentAxios(axios);
+
+        startJourney(def);
+        await journeyStep(def.name, 'book-job', () => {
+            const config = axios.requestHandlers[0]({ url: '/CallScreen/BookJob' });
+            expect(config.journeyStep).toBeInstanceOf(JourneyStepTag);
+            expect(config.journeyStart).toBe(1_000);
+
+            (globalThis.performance.now as jest.Mock).mockReturnValue(1_050);
+            const response = axios.responseOkHandlers[0]({ status: 200, config });
+            expect(response.status).toBe(200);
+        });
+        completeJourney(def.name);
+
+        expect(emitMock).toHaveBeenCalledTimes(1);
+        expect(emitMock.mock.calls[0][0].journey.outcome).toBe('good');
+    });
+
+    test('marks journey bad on 5xx via the rejection interceptor', async () => {
+        const axios = createAxiosMock();
+        instrumentAxios(axios);
+
+        startJourney(def);
+        await expect(
+            journeyStep(def.name, 'book-job', async () => {
+                const config = axios.requestHandlers[0]({ url: '/CallScreen/BookJob' });
+                (globalThis.performance.now as jest.Mock).mockReturnValue(1_020);
+                await axios.responseErrHandlers[0]({
+                    config,
+                    response: { status: 500 },
+                });
+            })
+        ).rejects.toMatchObject({ response: { status: 500 } });
+
+        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('honors an explicit journeyStep from step.tag()', async () => {
+        const axios = createAxiosMock();
+        instrumentAxios(axios);
+
+        startJourney(def);
+        await journeyStep(def.name, 'book-job', async step => {
+            const tagged = step.tag() as { journeyStep: unknown };
+            const config = axios.requestHandlers[0]({
+                url: '/CallScreen/BookJob',
+                journeyStep: tagged.journeyStep,
+            });
+            expect(config.journeyStep).toBe(tagged.journeyStep);
+
+            (globalThis.performance.now as jest.Mock).mockReturnValue(1_020);
+            await expect(
+                axios.responseErrHandlers[0]({
+                    config,
+                    response: { status: 503 },
+                })
+            ).rejects.toBeDefined();
+        });
+
+        expect(emitMock.mock.calls[0][0].journey.reason).toBe('request-error');
+    });
+
+    test('soft ambient: overlapping steps do not auto-stamp HTTP', async () => {
+        const other = { ...def, name: 'axios-journey-other' };
+        const axios = createAxiosMock();
+        instrumentAxios(axios);
+
+        startJourney(def);
+        startJourney(other);
+
+        let releaseA!: () => void;
+        const gateA = new Promise<void>(r => {
+            releaseA = r;
+        });
+
+        const stepA = journeyStep(def.name, 'load', async () => {
+            await gateA;
+        });
+
+        await journeyStep(other.name, 'book', async () => {
+            const config = axios.requestHandlers[0]({ url: '/CallScreen/BookJob' });
+            expect(config.journeyStep).toBeUndefined();
+
+            (globalThis.performance.now as jest.Mock).mockReturnValue(1_020);
+            await expect(
+                axios.responseErrHandlers[0]({
+                    config,
+                    response: { status: 500 },
+                })
+            ).rejects.toMatchObject({ response: { status: 500 } });
+        });
+
+        releaseA();
+        await stepA;
+
+        expect(emitMock).not.toHaveBeenCalled();
+        completeJourney(def.name);
+        completeJourney(other.name);
+        expect(emitMock).toHaveBeenCalledTimes(2);
+        expect(emitMock.mock.calls.every(c => c[0].journey.outcome === 'good')).toBe(true);
+    });
+
+    test('soft ambient: step.tag() still attributes during overlap', async () => {
+        const other = { ...def, name: 'axios-journey-tagged' };
+        const axios = createAxiosMock();
+        instrumentAxios(axios);
+
+        startJourney(def);
+        startJourney(other);
+
+        let releaseA!: () => void;
+        const gateA = new Promise<void>(r => {
+            releaseA = r;
+        });
+
+        const stepA = journeyStep(def.name, 'load', async () => {
+            await gateA;
+        });
+
+        await expect(
+            journeyStep(other.name, 'book', async step => {
+                const tagged = step.tag() as { journeyStep: unknown };
+                const config = axios.requestHandlers[0]({
+                    url: '/CallScreen/BookJob',
+                    journeyStep: tagged.journeyStep,
+                });
+                expect(config.journeyStep).toBe(tagged.journeyStep);
+
+                (globalThis.performance.now as jest.Mock).mockReturnValue(1_020);
+                await axios.responseErrHandlers[0]({
+                    config,
+                    response: { status: 500 },
+                });
+            })
+        ).rejects.toMatchObject({ response: { status: 500 } });
+
+        releaseA();
+        await stepA;
+
+        expect(emitMock).toHaveBeenCalledTimes(1);
+        expect(emitMock.mock.calls[0][0].journey.name).toBe(other.name);
+        expect(emitMock.mock.calls[0][0].journey.outcome).toBe('bad');
+        expect(emitMock.mock.calls[0][0].journey.reason).toBe('request-error');
+
+        completeJourney(def.name);
+    });
+
+    test('ignores responses with no journey step on the config', () => {
+        const axios = createAxiosMock();
+        instrumentAxios(axios);
+
+        // Outside a step — request interceptor finds no ambient step.
+        const config = axios.requestHandlers[0]({ url: '/orphan' });
+        expect(config.journeyStep).toBeUndefined();
+        axios.responseOkHandlers[0]({ status: 500, config });
+
+        expect(emitMock).not.toHaveBeenCalled();
+    });
+
+    test('non-axios errors without config are rethrown without reporting', async () => {
+        const axios = createAxiosMock();
+        instrumentAxios(axios);
+
+        await expect(axios.responseErrHandlers[0](new Error('boom'))).rejects.toThrow('boom');
+        expect(emitMock).not.toHaveBeenCalled();
+    });
+
+    test('falls back to performance.now when journeyStart is missing', async () => {
+        const axios = createAxiosMock();
+        instrumentAxios(axios);
+
+        startJourney(def);
+        await journeyStep(def.name, 'book-job', step => {
+            const tagged = step.tag() as { journeyStep: unknown };
+            const config = {
+                url: '/CallScreen/BookJob',
+                journeyStep: tagged.journeyStep,
+            };
+            (globalThis.performance.now as jest.Mock).mockReturnValue(1_200);
+            axios.responseOkHandlers[0]({ status: 200, config });
+        });
+        completeJourney(def.name);
+
+        expect(emitMock).toHaveBeenCalledTimes(1);
+        expect(emitMock.mock.calls[0][0].journey.outcome).toBe('good');
+    });
+
+    test('marks request-latency on a slow successful response', async () => {
+        const axios = createAxiosMock();
+        instrumentAxios(axios);
+
+        startJourney({ ...def, requestTimeoutMs: 50 });
+        await journeyStep(def.name, 'book-job', () => {
+            const config = axios.requestHandlers[0]({ url: '/CallScreen/BookJob' });
+            (globalThis.performance.now as jest.Mock).mockReturnValue(1_200);
+            axios.responseOkHandlers[0]({ status: 200, config });
+        });
+
+        expect(emitMock).toHaveBeenCalledTimes(1);
+        expect(emitMock.mock.calls[0][0].journey.outcome).toBe('bad');
+        expect(emitMock.mock.calls[0][0].journey.reason).toBe('request-latency');
+    });
+
+    test('does not mark bad on 4xx via the rejection interceptor', async () => {
+        const axios = createAxiosMock();
+        instrumentAxios(axios);
+
+        startJourney(def);
+        await journeyStep(def.name, 'book-job', async () => {
+            const config = axios.requestHandlers[0]({ url: '/CallScreen/BookJob' });
+            (globalThis.performance.now as jest.Mock).mockReturnValue(1_020);
+            await expect(
+                axios.responseErrHandlers[0]({
+                    config,
+                    response: { status: 400 },
+                })
+            ).rejects.toMatchObject({ response: { status: 400 } });
+        });
+        completeJourney(def.name);
+
+        expect(emitMock).toHaveBeenCalledTimes(1);
+        expect(emitMock.mock.calls[0][0].journey.outcome).toBe('good');
+    });
+
+    test('network errors without a response status mark request-error', async () => {
+        const axios = createAxiosMock();
+        instrumentAxios(axios);
+
+        startJourney(def);
+        await expect(
+            journeyStep(def.name, 'book-job', async () => {
+                const config = axios.requestHandlers[0]({ url: '/CallScreen/BookJob' });
+                (globalThis.performance.now as jest.Mock).mockReturnValue(1_020);
+                await axios.responseErrHandlers[0]({ config });
+            })
+        ).rejects.toBeDefined();
+
+        expect(emitMock).toHaveBeenCalledTimes(1);
+        expect(emitMock.mock.calls[0][0].journey.reason).toBe('request-error');
+    });
+
+    test('ok interceptor tolerates a missing response config', () => {
+        const axios = createAxiosMock();
+        instrumentAxios(axios);
+
+        expect(() => axios.responseOkHandlers[0]({ status: 200 })).not.toThrow();
+        expect(emitMock).not.toHaveBeenCalled();
+    });
+
+    test('rejection interceptor tolerates a missing error config', async () => {
+        const axios = createAxiosMock();
+        instrumentAxios(axios);
+
+        await expect(axios.responseErrHandlers[0]({ response: { status: 500 } })).rejects.toEqual({
+            response: { status: 500 },
+        });
+        expect(emitMock).not.toHaveBeenCalled();
+    });
+
+    test('uses config.baseURL when building the request key', async () => {
+        const axios = createAxiosMock();
+        instrumentAxios(axios);
+
+        startJourney({
+            ...def,
+            endpoints: [{ match: 'api.example.com/invoices', ignore: true }],
+        });
+        await journeyStep(def.name, 'book-job', async () => {
+            const config = axios.requestHandlers[0]({
+                url: '/invoices',
+                baseURL: 'https://api.example.com',
+            });
+            (globalThis.performance.now as jest.Mock).mockReturnValue(1_020);
+            await expect(
+                axios.responseErrHandlers[0]({
+                    config,
+                    response: { status: 500 },
+                })
+            ).rejects.toBeDefined();
+        });
+        completeJourney(def.name);
+
+        expect(emitMock).toHaveBeenCalledTimes(1);
+        expect(emitMock.mock.calls[0][0].journey.outcome).toBe('good');
+    });
+});

package/src/__tests__/config.test.ts

@@ -0,0 +1,261 @@
+/** @jest-environment jsdom */
+jest.mock('../sinks/datadog', () => ({
+    sendToDatadog: jest.fn(),
+}));
+
+jest.mock('../integrations/axios', () => ({
+    instrumentAxios: jest.fn(),
+}));
+
+jest.mock('../integrations/fetch', () => ({
+    instrumentFetch: jest.fn(() => jest.fn()),
+}));
+
+jest.mock('../integrations/jquery', () => ({
+    instrumentJquery: jest.fn(),
+    exposeAppJourney: jest.fn(),
+}));
+
+import {
+    configureJourney,
+    getRequestTimeouts,
+    longestEndpointMatch,
+    sortEndpointsByLongestMatch,
+} from '../config';
+import { resetJourney } from '../core';
+import { emitJourneyEvent } from '../core/registry';
+import type { JourneyEvent } from '../core/types';
+import { instrumentAxios } from '../integrations/axios';
+import { instrumentFetch } from '../integrations/fetch';
+import {
+    exposeAppJourney,
+    instrumentJquery,
+    type WindowWithAppJourney,
+} from '../integrations/jquery';
+import { sendToDatadog } from '../sinks/datadog';
+
+const instrumentAxiosMock = jest.mocked(instrumentAxios);
+const instrumentFetchMock = jest.mocked(instrumentFetch);
+const instrumentJqueryMock = jest.mocked(instrumentJquery);
+const exposeAppJourneyMock = jest.mocked(exposeAppJourney);
+
+describe('[journey] configureJourney / getRequestTimeouts', () => {
+    afterEach(() => {
+        resetJourney({
+            sinks: [sendToDatadog],
+            requestTimeouts: { defaultMs: 4_000, endpoints: [] },
+        });
+        instrumentAxiosMock.mockClear();
+        instrumentFetchMock.mockClear();
+        instrumentJqueryMock.mockClear();
+        exposeAppJourneyMock.mockClear();
+    });
+
+    test('defaults to 4s with empty endpoints', () => {
+        expect(getRequestTimeouts()).toEqual({ defaultMs: 4_000, endpoints: [] });
+    });
+
+    test('overrides the app-wide request timeout tier', () => {
+        configureJourney({
+            requestTimeouts: {
+                defaultMs: 2_000,
+                endpoints: [{ match: '/slow', timeoutMs: 8_000 }],
+            },
+        });
+
+        expect(getRequestTimeouts()).toEqual({
+            defaultMs: 2_000,
+            endpoints: [{ match: '/slow', timeoutMs: 8_000 }],
+        });
+    });
+
+    test('ignores configureJourney when requestTimeouts is omitted', () => {
+        configureJourney({ requestTimeouts: { defaultMs: 1_000, endpoints: [] } });
+        configureJourney({});
+        expect(getRequestTimeouts().defaultMs).toBe(1_000);
+    });
+
+    describe('with sinks', () => {
+        let payload: JourneyEvent;
+        let custom: jest.Mock;
+
+        beforeEach(() => {
+            jest.mocked(sendToDatadog).mockClear();
+            custom = jest.fn();
+            payload = {
+                journey: {
+                    name: 'test',
+                    team: 't',
+                    group: 'g',
+                    service: 's',
+                    outcome: 'good',
+                    durationMs: 1,
+                    steps: [],
+                },
+            };
+        });
+
+        test('replaces the sink list', () => {
+            configureJourney({ sinks: [custom] });
+            emitJourneyEvent(payload);
+
+            expect(custom).toHaveBeenCalledWith(payload);
+            expect(sendToDatadog).not.toHaveBeenCalled();
+        });
+
+        test('leaves sinks unchanged when sinks is omitted', () => {
+            configureJourney({ sinks: [custom] });
+            configureJourney({ requestTimeouts: { defaultMs: 2_000, endpoints: [] } });
+            emitJourneyEvent(payload);
+
+            expect(custom).toHaveBeenCalledWith(payload);
+            expect(sendToDatadog).not.toHaveBeenCalled();
+        });
+
+        test('disables emission when sinks is empty', () => {
+            configureJourney({ sinks: [] });
+            emitJourneyEvent(payload);
+
+            expect(sendToDatadog).not.toHaveBeenCalled();
+            expect(custom).not.toHaveBeenCalled();
+        });
+    });
+
+    describe('with transport wiring', () => {
+        const axios = {
+            defaults: {},
+            interceptors: { request: { use: jest.fn() }, response: { use: jest.fn() } },
+        };
+        const jquery = { ajaxPrefilter: jest.fn(), bind: jest.fn() } as never;
+        const fetchTarget = { fetch: jest.fn() };
+
+        test('instruments axios when provided', () => {
+            configureJourney({ axios: axios as never });
+
+            expect(instrumentAxiosMock).toHaveBeenCalledWith(axios);
+        });
+
+        test('instruments fetch with defaults when fetch is true', () => {
+            configureJourney({ fetch: true });
+
+            expect(instrumentFetchMock).toHaveBeenCalledWith({});
+        });
+
+        test('instruments fetch with options when provided', () => {
+            configureJourney({
+                fetch: { target: fetchTarget, baseURL: 'https://api.example.com' },
+            });
+
+            expect(instrumentFetchMock).toHaveBeenCalledWith({
+                target: fetchTarget,
+                baseURL: 'https://api.example.com',
+            });
+        });
+
+        test('instruments jquery when provided', () => {
+            configureJourney({ jquery });
+
+            expect(instrumentJqueryMock).toHaveBeenCalledWith(jquery);
+        });
+
+        test('exposes App.Journey when exposeAppJourney is true', () => {
+            configureJourney({ exposeAppJourney: true });
+
+            expect(exposeAppJourneyMock).toHaveBeenCalledWith(undefined);
+        });
+
+        test('exposes App.Journey on a custom target', () => {
+            const target = { App: {} } as WindowWithAppJourney;
+            configureJourney({ exposeAppJourney: target });
+
+            expect(exposeAppJourneyMock).toHaveBeenCalledWith(target);
+        });
+
+        test('skips transport helpers when omitted', () => {
+            configureJourney({ requestTimeouts: { defaultMs: 1_000, endpoints: [] } });
+
+            expect(instrumentAxiosMock).not.toHaveBeenCalled();
+            expect(instrumentFetchMock).not.toHaveBeenCalled();
+            expect(instrumentJqueryMock).not.toHaveBeenCalled();
+            expect(exposeAppJourneyMock).not.toHaveBeenCalled();
+        });
+    });
+});
+
+describe('longestEndpointMatch', () => {
+    // Lookup expects longest-match-first (configureJourney / startJourney sort for you).
+    const endpoints = [
+        { match: '/api/invoices', timeoutMs: 2_000 },
+        { match: '/api', timeoutMs: 1_000 },
+        { match: '/other', ignore: true },
+    ];
+
+    test('returns undefined for empty / undefined lists', () => {
+        expect(longestEndpointMatch(undefined, '/api')).toBeUndefined();
+        expect(longestEndpointMatch([], '/api')).toBeUndefined();
+    });
+
+    test('picks the longest matching prefix (first hit when sorted)', () => {
+        expect(longestEndpointMatch(endpoints, '/api/invoices/42')?.timeoutMs).toBe(2_000);
+        expect(longestEndpointMatch(endpoints, '/api/jobs')?.timeoutMs).toBe(1_000);
+    });
+
+    test('returns undefined when nothing matches', () => {
+        expect(longestEndpointMatch(endpoints, '/health')).toBeUndefined();
+    });
+
+    test('requires a path boundary after the prefix', () => {
+        const user = [{ match: '/api/user', timeoutMs: 1_000 }];
+        expect(longestEndpointMatch(user, '/api/user')?.timeoutMs).toBe(1_000);
+        expect(longestEndpointMatch(user, '/api/user/42')?.timeoutMs).toBe(1_000);
+        expect(longestEndpointMatch(user, '/api/user-preferences')).toBeUndefined();
+        expect(longestEndpointMatch(user, '/api/users')).toBeUndefined();
+
+        const trailed = [{ match: '/api/user/', timeoutMs: 2_000 }];
+        expect(longestEndpointMatch(trailed, '/api/user/42')?.timeoutMs).toBe(2_000);
+    });
+});
+
+describe('configureJourney endpoint ordering', () => {
+    afterEach(() => {
+        resetJourney({
+            sinks: [sendToDatadog],
+            requestTimeouts: { defaultMs: 4_000, endpoints: [] },
+        });
+    });
+
+    test('stores endpoints longest-match-first', () => {
+        configureJourney({
+            requestTimeouts: {
+                defaultMs: 4_000,
+                endpoints: [
+                    { match: '/api', timeoutMs: 1_000 },
+                    { match: '/api/invoices', timeoutMs: 2_000 },
+                ],
+            },
+        });
+
+        expect(getRequestTimeouts().endpoints?.map(e => e.match)).toEqual([
+            '/api/invoices',
+            '/api',
+        ]);
+    });
+});
+
+describe('[journey] sortEndpointsByLongestMatch', () => {
+    test('returns undefined for undefined input', () => {
+        expect(sortEndpointsByLongestMatch(undefined)).toBeUndefined();
+    });
+
+    test('returns a copy for a single endpoint', () => {
+        const only = [{ match: '/api', timeoutMs: 1_000 }];
+        const sorted = sortEndpointsByLongestMatch(only);
+
+        expect(sorted).toEqual(only);
+        expect(sorted).not.toBe(only);
+    });
+
+    test('returns an empty array for an empty list', () => {
+        expect(sortEndpointsByLongestMatch([])).toEqual([]);
+    });
+});