@servicetitan/journey 1.0.0

package/src/__tests__/registry.test.ts

@@ -0,0 +1,265 @@
+/** @jest-environment jsdom */
+import { baseJourneyDef, lastJourney, useJourneyTestRuntime } from '../__mocks__/test-runtime';
+import {
+    completeJourney,
+    excludeJourney,
+    failJourney,
+    firstOpenJourney,
+    journeyStep,
+    setJourneyTags,
+    startJourney,
+} from '../core';
+
+const emitMock = jest.fn();
+const baseDef = { ...baseJourneyDef, name: 'registry-api' };
+const otherDef = { ...baseJourneyDef, name: 'registry-other' };
+
+describe('[journey] registry', () => {
+    useJourneyTestRuntime(emitMock);
+
+    describe('firstOpenJourney', () => {
+        const names = [baseDef.name, otherDef.name];
+
+        const subject = () => firstOpenJourney(names);
+
+        describe('when none are open', () => {
+            test('returns null', () => {
+                expect(subject()).toBeNull();
+            });
+        });
+
+        describe('when only the second name is open', () => {
+            beforeEach(() => {
+                startJourney(otherDef);
+            });
+
+            test('returns that name', () => {
+                expect(subject()).toBe(otherDef.name);
+            });
+        });
+
+        describe('when both are open', () => {
+            beforeEach(() => {
+                startJourney(otherDef);
+                startJourney(baseDef);
+            });
+
+            test('returns the first match in order', () => {
+                expect(subject()).toBe(baseDef.name);
+                expect(firstOpenJourney([otherDef.name, baseDef.name])).toBe(otherDef.name);
+            });
+        });
+    });
+
+    describe('completeJourney', () => {
+        describe('with tags', () => {
+            beforeEach(() => {
+                startJourney(baseDef);
+            });
+
+            const subject = () => completeJourney(baseDef.name, { 'lead.id': 7 });
+
+            test('emits good with tags', () => {
+                subject();
+
+                expect(lastJourney(emitMock).outcome).toBe('good');
+                expect(lastJourney(emitMock).tags['lead.id']).toBe(7);
+            });
+        });
+
+        describe('with null name', () => {
+            const subject = () => completeJourney(null, { a: 1 });
+
+            test('is a no-op', () => {
+                expect(() => subject()).not.toThrow();
+                expect(emitMock).not.toHaveBeenCalled();
+            });
+        });
+
+        describe('when already closed', () => {
+            beforeEach(async () => {
+                startJourney(baseDef);
+                await journeyStep(baseDef.name, 'do-work', step => {
+                    step.complete();
+                });
+            });
+
+            const subject = () => completeJourney(baseDef.name, { ignored: true });
+
+            test('does not emit again', () => {
+                subject();
+
+                expect(emitMock).toHaveBeenCalledTimes(1);
+            });
+        });
+
+        describe('after a fail', () => {
+            beforeEach(async () => {
+                startJourney(baseDef);
+                await journeyStep(baseDef.name, 'do-work', step => {
+                    step.fail('validation');
+                });
+            });
+
+            const subject = () => completeJourney(baseDef.name, { ignored: true });
+
+            test('does not flip the outcome', () => {
+                subject();
+
+                expect(emitMock).toHaveBeenCalledTimes(1);
+                expect(lastJourney(emitMock).outcome).toBe('bad');
+            });
+        });
+    });
+
+    describe('startJourney', () => {
+        describe('when restarting the same name', () => {
+            beforeEach(() => {
+                startJourney(baseDef);
+            });
+
+            const subject = () => startJourney(baseDef);
+
+            test('excludes the prior open journey', () => {
+                subject();
+
+                expect(lastJourney(emitMock).outcome).toBe('excluded');
+            });
+        });
+
+        describe('when restarting after a bad close', () => {
+            beforeEach(async () => {
+                startJourney(baseDef);
+                await journeyStep(baseDef.name, 'do-work', step => {
+                    step.fail('validation');
+                });
+            });
+
+            const subject = () => startJourney(baseDef);
+
+            test('opens fresh without a second exclude', () => {
+                subject();
+
+                expect(emitMock).toHaveBeenCalledTimes(1);
+                completeJourney(baseDef.name);
+                expect(lastJourney(emitMock).outcome).toBe('good');
+            });
+        });
+
+        describe('with static def tags', () => {
+            const subject = () => {
+                startJourney({ ...baseDef, tags: { plan: 'pro' } });
+                completeJourney(baseDef.name, { 'job.id': 5 });
+            };
+
+            test('merges into the event', () => {
+                subject();
+
+                expect(lastJourney(emitMock).tags).toEqual({ 'plan': 'pro', 'job.id': 5 });
+            });
+        });
+    });
+
+    describe('failJourney', () => {
+        beforeEach(() => {
+            startJourney(baseDef);
+        });
+
+        const subject = () => failJourney(baseDef.name, 'manual-bad');
+
+        test('marks bad', () => {
+            subject();
+
+            expect(lastJourney(emitMock).outcome).toBe('bad');
+            expect(lastJourney(emitMock).reason).toBe('manual-bad');
+        });
+
+        describe('when called twice', () => {
+            test('keeps the first reason', () => {
+                failJourney(baseDef.name, 'first-breach');
+                failJourney(baseDef.name, 'second-breach');
+
+                expect(emitMock).toHaveBeenCalledTimes(1);
+                expect(lastJourney(emitMock).reason).toBe('first-breach');
+            });
+        });
+    });
+
+    describe('excludeJourney', () => {
+        describe('with a clean journey', () => {
+            beforeEach(() => {
+                startJourney(otherDef);
+            });
+
+            const subject = () => excludeJourney(otherDef.name);
+
+            test('marks excluded', () => {
+                subject();
+
+                expect(lastJourney(emitMock).outcome).toBe('excluded');
+            });
+        });
+
+        describe('after a breach', () => {
+            beforeEach(async () => {
+                startJourney(baseDef);
+                await journeyStep(baseDef.name, 'do-work', step => {
+                    step.fail('validation');
+                });
+                emitMock.mockClear();
+            });
+
+            const subject = () => excludeJourney(baseDef.name);
+
+            test('does not emit again', () => {
+                subject();
+
+                expect(emitMock).not.toHaveBeenCalled();
+            });
+        });
+
+        describe('when past the journey budget', () => {
+            beforeEach(() => {
+                jest.spyOn(globalThis.performance, 'now').mockReturnValue(1_000);
+                startJourney({ ...baseDef, timeoutMs: 50 });
+                (globalThis.performance.now as jest.Mock).mockReturnValue(1_100);
+            });
+
+            afterEach(() => {
+                jest.restoreAllMocks();
+            });
+
+            const subject = () => excludeJourney(baseDef.name);
+
+            test('forces bad with journey-timeout', () => {
+                subject();
+
+                expect(lastJourney(emitMock).outcome).toBe('bad');
+                expect(lastJourney(emitMock).reason).toBe('journey-timeout');
+            });
+        });
+    });
+
+    describe('setJourneyTags', () => {
+        describe('with null name', () => {
+            const subject = () => setJourneyTags(null, { a: 1 });
+
+            test('is a no-op', () => {
+                expect(() => subject()).not.toThrow();
+            });
+        });
+
+        describe('with a closed journey', () => {
+            beforeEach(() => {
+                startJourney(baseDef);
+                completeJourney(baseDef.name);
+            });
+
+            const subject = () => setJourneyTags(baseDef.name, { a: 1 });
+
+            test('is a no-op', () => {
+                expect(() => subject()).not.toThrow();
+            });
+        });
+    });
+});

package/src/__tests__/request-key.test.ts

@@ -0,0 +1,81 @@
+/** @jest-environment jsdom */
+import { requestKey } from '../integrations/request-key';
+
+describe('[journey] requestKey', () => {
+    // Do not redefine window.location — jsdom's property is non-configurable.
+    const pageOrigin = window.location.origin;
+
+    describe('with a same-origin absolute url', () => {
+        const subject = () => requestKey(`${pageOrigin}/api/jobs`, undefined, undefined);
+
+        test('returns the pathname', () => {
+            expect(subject()).toBe('/api/jobs');
+        });
+    });
+
+    describe('with a relative url', () => {
+        const subject = () => requestKey('/CallScreen/BookJob', undefined, undefined);
+
+        test('returns the pathname against the page origin', () => {
+            expect(subject()).toBe('/CallScreen/BookJob');
+        });
+    });
+
+    describe('with a cross-origin url', () => {
+        const subject = () => requestKey('https://pdf.vendor.com/render', undefined, undefined);
+
+        test('returns host/path', () => {
+            expect(subject()).toBe('pdf.vendor.com/render');
+        });
+    });
+
+    describe('with configBaseURL and instanceBaseURL', () => {
+        const subject = () =>
+            requestKey('/invoices', 'https://api.example.com', 'https://other.example.com');
+
+        test('prefers configBaseURL for resolution', () => {
+            expect(subject()).toBe('api.example.com/invoices');
+        });
+    });
+
+    describe('with only instanceBaseURL', () => {
+        const subject = () => requestKey('/invoices', undefined, 'https://api.example.com');
+
+        test('uses the instance home', () => {
+            expect(subject()).toBe('/invoices');
+        });
+    });
+
+    describe('with a cross-origin url against a different instance home', () => {
+        const subject = () =>
+            requestKey('https://pdf.vendor.com/render', undefined, 'https://api.example.com');
+
+        test('returns host/path', () => {
+            expect(subject()).toBe('pdf.vendor.com/render');
+        });
+    });
+
+    describe('when URL construction fails', () => {
+        const subject = () => requestKey('http://[', undefined, undefined);
+
+        test('returns the raw url', () => {
+            expect(subject()).toBe('http://[');
+        });
+    });
+
+    describe('when url is undefined and construction fails', () => {
+        const subject = () => requestKey(undefined, '::not-a-url::', undefined);
+
+        test('returns an empty string', () => {
+            expect(subject()).toBe('');
+        });
+    });
+
+    describe('when instanceBaseURL is invalid', () => {
+        const subject = () => requestKey(`${pageOrigin}/ok`, pageOrigin, '::bad::');
+
+        test('falls back to the page origin', () => {
+            expect(subject()).toBe('/ok');
+        });
+    });
+});

package/src/__tests__/requests.test.ts

@@ -0,0 +1,337 @@
+/** @jest-environment jsdom */
+import { baseJourneyDef, lastJourney, useJourneyTestRuntime } from '../__mocks__/test-runtime';
+import { configureJourney } from '../config';
+import {
+    completeJourney,
+    journeyStep,
+    reportBackendRequest,
+    resolveJourneyStep,
+    startJourney,
+    type JourneyDef,
+    type JourneyStepRef,
+} from '../core';
+
+const emitMock = jest.fn();
+const baseDef = { ...baseJourneyDef, name: 'requests-journey' };
+
+describe('[journey] reportBackendRequest', () => {
+    let stepRef: JourneyStepRef | undefined;
+    let status: number | undefined;
+    let durationMs: number;
+    let key: string;
+
+    useJourneyTestRuntime(emitMock);
+
+    beforeEach(() => {
+        stepRef = undefined;
+        status = 500;
+        durationMs = 10;
+        key = '/api';
+    });
+
+    const subject = () => reportBackendRequest(stepRef, status, durationMs, key);
+
+    async function withOpenStep(
+        run: (ref: JourneyStepRef) => void | Promise<void>,
+        def: JourneyDef = { ...baseDef, requestTimeoutMs: 5_000 }
+    ) {
+        startJourney(def);
+        await journeyStep(baseDef.name, 'do-work', async step => {
+            stepRef = resolveJourneyStep((step.tag() as { journeyStep: unknown }).journeyStep);
+            await run(stepRef!);
+        });
+    }
+
+    describe('without a step ref', () => {
+        beforeEach(() => {
+            stepRef = undefined;
+        });
+
+        test('is a no-op', () => {
+            expect(() => subject()).not.toThrow();
+            expect(emitMock).not.toHaveBeenCalled();
+        });
+    });
+
+    describe('when status is a 4xx', () => {
+        beforeEach(() => {
+            status = 404;
+        });
+
+        test('does not mark the journey bad', async () => {
+            await withOpenStep(() => {
+                subject();
+            });
+            completeJourney(baseDef.name);
+
+            expect(lastJourney(emitMock).outcome).toBe('good');
+        });
+    });
+
+    describe('when the request is under the latency threshold', () => {
+        beforeEach(() => {
+            status = 200;
+            durationMs = 10;
+        });
+
+        test('does not mark the journey bad', async () => {
+            await withOpenStep(() => {
+                subject();
+            });
+            completeJourney(baseDef.name);
+
+            expect(lastJourney(emitMock).outcome).toBe('good');
+        });
+    });
+
+    describe('when the request is slow', () => {
+        beforeEach(() => {
+            status = 200;
+            durationMs = 200;
+            key = '/slow';
+        });
+
+        test('marks request-latency', async () => {
+            await withOpenStep(
+                () => {
+                    subject();
+                },
+                { ...baseDef, requestTimeoutMs: 50 }
+            );
+
+            expect(lastJourney(emitMock).reason).toBe('request-latency');
+        });
+    });
+
+    describe('when status is a 5xx', () => {
+        beforeEach(() => {
+            status = 502;
+        });
+
+        test('records httpStatus on the step', async () => {
+            await withOpenStep(() => {
+                subject();
+            });
+
+            expect(lastJourney(emitMock).steps[0].httpStatus).toBe(502);
+            expect(lastJourney(emitMock).steps[0].reason).toBe('request-error');
+        });
+    });
+
+    describe('when the step already has a reason', () => {
+        test('preserves the first reason', async () => {
+            await withOpenStep(ref => {
+                ref.reason = 'step-error';
+                status = 502;
+                subject();
+            });
+
+            expect(lastJourney(emitMock).steps[0].reason).toBe('step-error');
+            expect(lastJourney(emitMock).reason).toBe('request-error');
+        });
+    });
+
+    describe('when status is undefined', () => {
+        beforeEach(() => {
+            status = undefined;
+        });
+
+        test('marks request-error without httpStatus', async () => {
+            await withOpenStep(() => {
+                subject();
+            });
+
+            expect(lastJourney(emitMock).reason).toBe('request-error');
+            expect(lastJourney(emitMock).steps[0].httpStatus).toBeUndefined();
+        });
+    });
+
+    describe('when the journey endpoint is ignored', () => {
+        test('never marks the journey bad', async () => {
+            await withOpenStep(
+                () => {
+                    status = 500;
+                    key = '/flaky/thing';
+                    subject();
+                },
+                {
+                    ...baseDef,
+                    requestTimeoutMs: 5_000,
+                    endpoints: [{ match: '/flaky', ignore: true }],
+                }
+            );
+            completeJourney(baseDef.name);
+
+            expect(lastJourney(emitMock).outcome).toBe('good');
+        });
+    });
+
+    describe('when a journey endpoint timeoutMs is 0', () => {
+        test('falls through to the journey requestTimeoutMs', async () => {
+            startJourney({
+                ...baseDef,
+                requestTimeoutMs: 30,
+                endpoints: [{ match: '/special', timeoutMs: 0 }],
+            });
+
+            await journeyStep(baseDef.name, 'do-work', step => {
+                stepRef = resolveJourneyStep((step.tag() as { journeyStep: unknown }).journeyStep);
+                status = 200;
+                durationMs = 100;
+                key = '/special/path';
+                subject();
+            });
+
+            expect(lastJourney(emitMock).reason).toBe('request-latency');
+        });
+    });
+
+    describe('when journey endpoint timeoutMs is set', () => {
+        test('wins over the journey requestTimeoutMs', async () => {
+            await withOpenStep(
+                () => {
+                    status = 200;
+                    durationMs = 50;
+                    key = '/special/path';
+                    subject();
+                },
+                {
+                    ...baseDef,
+                    requestTimeoutMs: 5_000,
+                    endpoints: [{ match: '/special', timeoutMs: 20 }],
+                }
+            );
+
+            expect(lastJourney(emitMock).reason).toBe('request-latency');
+        });
+    });
+
+    describe('when the journey endpoint ignore overrides the app-wide policy', () => {
+        beforeEach(() => {
+            configureJourney({
+                requestTimeouts: {
+                    defaultMs: 4_000,
+                    endpoints: [{ match: '/flaky', ignore: true }],
+                },
+            });
+        });
+
+        test('journey ignore:false still counts errors', async () => {
+            await withOpenStep(
+                () => {
+                    status = 500;
+                    key = '/flaky/x';
+                    subject();
+                },
+                {
+                    ...baseDef,
+                    requestTimeoutMs: 5_000,
+                    endpoints: [{ match: '/flaky', ignore: false }],
+                }
+            );
+
+            expect(lastJourney(emitMock).reason).toBe('request-error');
+        });
+    });
+
+    describe('when only app-wide endpoint policies apply', () => {
+        beforeEach(() => {
+            configureJourney({
+                requestTimeouts: {
+                    defaultMs: 4_000,
+                    endpoints: [
+                        { match: '/ignored', ignore: true },
+                        { match: '/tight', timeoutMs: 30 },
+                    ],
+                },
+            });
+        });
+
+        test('honors app ignore', async () => {
+            await withOpenStep(() => {
+                status = 500;
+                key = '/ignored/x';
+                subject();
+            });
+            completeJourney(baseDef.name);
+
+            expect(lastJourney(emitMock).outcome).toBe('good');
+        });
+
+        test('honors app timeoutMs', async () => {
+            await withOpenStep(() => {
+                status = 200;
+                durationMs = 100;
+                key = '/tight/x';
+                subject();
+            });
+
+            expect(lastJourney(emitMock).reason).toBe('request-latency');
+        });
+    });
+
+    describe('when app endpoint timeoutMs is 0', () => {
+        beforeEach(() => {
+            configureJourney({
+                requestTimeouts: {
+                    defaultMs: 40,
+                    endpoints: [{ match: '/loose', timeoutMs: 0 }],
+                },
+            });
+        });
+
+        test('falls through to defaultMs', async () => {
+            startJourney(baseDef);
+
+            await journeyStep(baseDef.name, 'do-work', step => {
+                stepRef = resolveJourneyStep((step.tag() as { journeyStep: unknown }).journeyStep);
+                status = 200;
+                durationMs = 100;
+                key = '/loose/x';
+                subject();
+            });
+
+            expect(lastJourney(emitMock).reason).toBe('request-latency');
+        });
+    });
+
+    describe('when the journey has no requestTimeoutMs', () => {
+        beforeEach(() => {
+            configureJourney({ requestTimeouts: { defaultMs: 40, endpoints: [] } });
+        });
+
+        test('uses the app defaultMs', async () => {
+            startJourney(baseDef);
+
+            await journeyStep(baseDef.name, 'do-work', step => {
+                stepRef = resolveJourneyStep((step.tag() as { journeyStep: unknown }).journeyStep);
+                status = 200;
+                durationMs = 100;
+                key = '/any';
+                subject();
+            });
+
+            expect(lastJourney(emitMock).reason).toBe('request-latency');
+        });
+    });
+
+    describe('against a closed journey step ref', () => {
+        let closedRef: JourneyStepRef | undefined;
+
+        beforeEach(async () => {
+            await withOpenStep(ref => {
+                closedRef = ref;
+            });
+            completeJourney(baseDef.name);
+            emitMock.mockClear();
+            stepRef = closedRef;
+            status = 500;
+        });
+
+        test('is a no-op', () => {
+            subject();
+
+            expect(emitMock).not.toHaveBeenCalled();
+        });
+    });
+});