diff --git a/src/platform/onboarding/onboardingTourStore.test.ts b/src/platform/onboarding/onboardingTourStore.test.ts index 8299c17b4fd..87446fca92c 100644 --- a/src/platform/onboarding/onboardingTourStore.test.ts +++ b/src/platform/onboarding/onboardingTourStore.test.ts @@ -247,6 +247,104 @@ describe('onboardingTourStore', () => { expect(skipped?.[1]).toMatchObject({ skip_reason: 'user' }) }) + describe('the ending it hands on', () => { + it('has none to report before a tour has ended', async () => { + const store = mountStore() + store.replayTour('appMode') + await nextTick() + + expect( + store.lastEnding, + 'a running tour has not ended, so nothing may act on how it did' + ).toBeNull() + }) + + it('records a deliberate dismissal as the user’s own', async () => { + const store = mountStore() + store.replayTour('appMode') + await nextTick() + + store.skip() + + expect(store.lastEnding).toEqual({ + tour: 'appMode', + outcome: 'skipped', + skipReason: 'user' + }) + }) + + it('records a tour torn down by a target that never mounted', async () => { + vi.useFakeTimers() + const store = mountStore() + store.replayTour('appMode') + await vi.advanceTimersByTimeAsync(0) + store.next() + // The deferred target (inputs list) is never registered; exhaust the wait. + await vi.advanceTimersByTimeAsync(8000) + + expect( + store.lastEnding, + 'whatever follows the tour has to tell this apart from a finished one' + ).toEqual({ + tour: 'appMode', + outcome: 'skipped', + skipReason: 'target_timeout' + }) + }) + + it('records a tour that lost the context its steps point at', async () => { + settings.store.set(TOUR_SEEN_SETTING, ['appMode']) + const store = mountStore() + enterApp('app', false) + await nextTick() + store.replayTour('appMode') + await nextTick() + + enterApp('graph', false) + await nextTick() + + expect(store.lastEnding).toEqual({ + tour: 'appMode', + outcome: 'skipped', + skipReason: 'trigger_lost' + }) + }) + + it('records a walked-to-the-end tour with no skip reason', async () => { + registerAppModeTargets() + const store = mountStore() + store.replayTour('appMode') + await nextTick() + + // Capped so a stuck tour fails instead of hanging. + for (let i = 0; i < 12 && !seenTours().includes('appMode'); i++) { + store.next() + await nextTick() + } + + expect(store.lastEnding).toEqual({ + tour: 'appMode', + outcome: 'completed' + }) + }) + + it('drops the last ending as soon as a new run is requested', async () => { + const store = mountStore() + store.replayTour('appMode') + await nextTick() + store.skip() + expect(store.lastEnding).not.toBeNull() + + store.replayTour('appMode') + await nextTick() + + expect( + store.lastEnding, + 'a run still going has no ending, and the last one does not speak for it' + ).toBeNull() + }) + }) + it('holds the card on its step while a deferred target is awaited', async () => { vi.useFakeTimers() const store = mountStore() diff --git a/src/platform/onboarding/onboardingTourStore.ts b/src/platform/onboarding/onboardingTourStore.ts index bd53394a62a..7ab68e826ac 100644 --- a/src/platform/onboarding/onboardingTourStore.ts +++ b/src/platform/onboarding/onboardingTourStore.ts @@ -28,6 +28,20 @@ import { useTourTriggers } from './useTourTriggers' const DEFER_TIMEOUT_MS = 8000 +/** + * How the last run of a tour ended. Whatever follows a tour has to know which + * ending it is following: "a tour ran" cannot tell a tour walked to the end + * apart from one the user waved away on step 1, or one a missing target tore + * down. + */ +export type TourEnding = + | { tour: EntryPath; outcome: 'completed' } + | { + tour: EntryPath + outcome: 'skipped' + skipReason: OnboardingTourSkipReason + } + /** Empty when a runtime resolver fails, so one bad graph costs only its own tour. */ async function resolveDefinition( definition: TourDefinition @@ -51,6 +65,7 @@ export const useOnboardingTourStore = defineStore('onboardingTour', () => { const telemetry = useTelemetry() const state = shallowRef(IDLE) + const lastEnding = shallowRef(null) let stepController: AbortController | null = null let lastRun = 0 @@ -283,6 +298,11 @@ export const useOnboardingTourStore = defineStore('onboardingTour', () => { if (!dispatch({ type: 'ended', run })) return + if (ending.tour) + lastEnding.value = + outcome === 'skipped' + ? { tour: ending.tour, outcome, skipReason } + : { tour: ending.tour, outcome } trackTour( outcome, outcome === 'skipped' ? skipReason : undefined, @@ -330,6 +350,8 @@ export const useOnboardingTourStore = defineStore('onboardingTour', () => { if (!definition) return false const run = nextRun() if (!dispatch({ type: 'requested', tour: entryPath, run })) return false + // A new run has no ending yet; the one before it must not speak for it. + lastEnding.value = null const built = await resolveDefinition(definition) const resolved = resolveSteps(built.steps, targetMounted) if (!resolved.length) { @@ -373,6 +395,7 @@ export const useOnboardingTourStore = defineStore('onboardingTour', () => { return { activeTour: readonly(activeTour), + lastEnding: readonly(lastEnding), step, isLast, canGoBack, diff --git a/src/renderer/extensions/firstRunTour/nudge/FirstRunTourNudge.test.ts b/src/renderer/extensions/firstRunTour/nudge/FirstRunTourNudge.test.ts index b9e59941ee5..b02f06e31ec 100644 --- a/src/renderer/extensions/firstRunTour/nudge/FirstRunTourNudge.test.ts +++ b/src/renderer/extensions/firstRunTour/nudge/FirstRunTourNudge.test.ts @@ -15,7 +15,7 @@ const mocks = await vi.hoisted(async () => { const { ref } = await import('vue') return { nudgeArmed: ref(false), - tourWasShown: ref(true), + tourWasCompleted: ref(true), openDialogs: ref([]), dismissNudge: vi.fn(() => { mocks.nudgeArmed.value = false @@ -28,7 +28,7 @@ const mocks = await vi.hoisted(async () => { vi.mock('../tour/useFirstRunTourController', () => ({ useFirstRunTourController: () => ({ nudgeArmed: mocks.nudgeArmed, - tourWasShown: mocks.tourWasShown, + tourWasCompleted: mocks.tourWasCompleted, dismissNudge: mocks.dismissNudge }) })) @@ -71,6 +71,7 @@ describe('FirstRunTourNudge', () => { vi.clearAllMocks() vi.useFakeTimers() mocks.nudgeArmed.value = false + mocks.tourWasCompleted.value = true mocks.openDialogs.value = [] }) @@ -157,19 +158,43 @@ describe('FirstRunTourNudge', () => { ).toHaveLength(1) }) - it('offers no congratulation for a tour that never appeared', async () => { - mocks.tourWasShown.value = false + it('congratulates a tour the user walked to the end', async () => { + mocks.tourWasCompleted.value = true + mocks.nudgeArmed.value = true + renderNudge() + await vi.advanceTimersByTimeAsync(APPEAR_DELAY_MS) + + expect(screen.getByText(nudgeCopy.ran.title)).toBeTruthy() + }) + + it('offers no congratulation for a tour nobody finished', async () => { + mocks.tourWasCompleted.value = false mocks.nudgeArmed.value = true renderNudge() await vi.advanceTimersByTimeAsync(APPEAR_DELAY_MS) expect( screen.queryByText(nudgeCopy.ran.title), - 'a user whose tour never ran made nothing to be congratulated for' + 'a user who skipped, was cut off or saw no tour made no first result' ).toBeNull() expect(screen.getByText(nudgeCopy.noTour.title)).toBeTruthy() }) + it.for([{ finished: true }, { finished: false }])( + 'appears whether or not the tour finished ($finished)', + async ({ finished }) => { + mocks.tourWasCompleted.value = finished + mocks.nudgeArmed.value = true + renderNudge() + await vi.advanceTimersByTimeAsync(APPEAR_DELAY_MS) + + expect( + nudge(), + 'the copy is all that the ending changes; the way forward is offered either way' + ).not.toBeNull() + } + ) + it('stays gone once the user closes it', async () => { const user = userEvent.setup({ advanceTimers: vi.advanceTimersByTime }) mocks.nudgeArmed.value = true diff --git a/src/renderer/extensions/firstRunTour/nudge/FirstRunTourNudge.vue b/src/renderer/extensions/firstRunTour/nudge/FirstRunTourNudge.vue index 083935f6ab5..3d299bcf28f 100644 --- a/src/renderer/extensions/firstRunTour/nudge/FirstRunTourNudge.vue +++ b/src/renderer/extensions/firstRunTour/nudge/FirstRunTourNudge.vue @@ -70,15 +70,17 @@ const NUDGE_IMAGE = '/assets/images/og-image.png' const APPEAR_DELAY_MS = 1500 const { t } = useI18n() -const { nudgeArmed, tourWasShown, dismissNudge } = useFirstRunTourController() +const { nudgeArmed, tourWasCompleted, dismissNudge } = + useFirstRunTourController() const dialogStore = useDialogStore() const telemetry = useTelemetry() const titleId = useId() -// A tour that never appeared made nothing to congratulate the user for. +// Only a tour walked to the end made a first result to congratulate; every +// other ending still gets a nudge, pointing at the templates instead. const copyKey = computed( () => - `onboardingCoachmarks.firstRun.nudge.${tourWasShown.value ? 'ran' : 'noTour'}` + `onboardingCoachmarks.firstRun.nudge.${tourWasCompleted.value ? 'ran' : 'noTour'}` ) const onScreen = ref(false) diff --git a/src/renderer/extensions/firstRunTour/tour/useFirstRunTourController.test.ts b/src/renderer/extensions/firstRunTour/tour/useFirstRunTourController.test.ts index 038f76c1b63..6d4b038fd85 100644 --- a/src/renderer/extensions/firstRunTour/tour/useFirstRunTourController.test.ts +++ b/src/renderer/extensions/firstRunTour/tour/useFirstRunTourController.test.ts @@ -5,10 +5,12 @@ import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest' import { effectScope, nextTick, ref } from 'vue' import type { EffectScope, Ref } from 'vue' +import type { TourEnding } from '@/platform/onboarding/onboardingTourStore' import type { CoachStep, SpotlightStep } from '@/platform/onboarding/onboardingTours' +import type { OnboardingTourSkipReason } from '@/platform/telemetry/types' const TOUR_WORKFLOW = { path: 'tour.json' } const OTHER_WORKFLOW = { path: 'other.json' } @@ -28,6 +30,7 @@ const mocks = vi.hoisted(() => ({ releaseFirstRunTargets: vi.fn(), engine: { activeTour: null as string | null, + lastEnding: null as TourEnding | null, step: null as CoachStep | null, isLast: false, startTour: vi.fn(), @@ -159,6 +162,36 @@ async function tourOnRunStep() { return { controller, started: await starting } } +/** The engine ending the tour and recording how, the way `finish()` leaves it. */ +function endTour(ending: TourEnding) { + mocks.engine.lastEnding = ending + mocks.engine.activeTour = null + mocks.engine.step = null + return nextTick() +} + +const COMPLETED: TourEnding = { tour: 'firstRun', outcome: 'completed' } + +function skippedBecause(skipReason: OnboardingTourSkipReason): TourEnding { + return { tour: 'firstRun', outcome: 'skipped', skipReason } +} + +/** Every ending short of walking the tour to the end. */ +const UNFINISHED_ENDINGS: { named: string; ending: TourEnding }[] = [ + { named: 'the user waved away on step 1', ending: skippedBecause('user') }, + { + named: 'a missing target tore down', + ending: skippedBecause('target_timeout') + }, + { named: 'the paywall parked', ending: skippedBecause('postponed') }, + { named: 'a lost context ended', ending: skippedBecause('trigger_lost') } +] + +const EVERY_ENDING: { named: string; ending: TourEnding }[] = [ + { named: 'the user walked to the end', ending: COMPLETED }, + ...UNFINISHED_ENDINGS +] + function finishRun(workflow: unknown, status: string) { mocks.workflowStatus.value = new Map(mocks.workflowStatus.value).set( workflow, @@ -209,6 +242,7 @@ describe('useFirstRunTourController', () => { mocks.vueNodesEnabled = true mocks.steps = [] mocks.engine.activeTour = null + mocks.engine.lastEnding = null mocks.engine.step = null mocks.engine.isLast = false }) @@ -644,11 +678,52 @@ describe('useFirstRunTourController', () => { ).toBe(false) }) + it('congratulates a tour the user walked to the end', async () => { + const { controller } = await tourOnRunStep() + + await endTour(COMPLETED) + + expect(controller.tourWasCompleted.value).toBe(true) + }) + + it.for(UNFINISHED_ENDINGS)( + 'congratulates nobody for a tour $named', + async ({ ending }) => { + const { controller } = await tourOnRunStep() + + await endTour(ending) + + expect( + controller.tourWasCompleted.value, + 'a tour the user never walked to the end made no first result to congratulate' + ).toBe(false) + } + ) + + it.for(EVERY_ENDING)( + 'still offers the nudge after a tour $named', + async ({ ending }) => { + const { controller } = await tourOnRunStep() + + await endTour(ending) + + expect( + controller.nudgeArmed.value, + 'suppressing the nudge takes the way forward from the user who most needs it (#14144)' + ).toBe(true) + } + ) + it('congratulates nobody when the tour never appeared', async () => { mocks.steps = [] mocks.activeWorkflow.value = TOUR_WORKFLOW mocks.engine.startTour.mockImplementation(async () => { await resolveRegisteredTour() + // The store requests the run, resolves no steps and returns to idle, so + // nothing ever calls `finish()` and no ending is recorded. + mocks.engine.activeTour = 'firstRun' + await nextTick() + mocks.engine.activeTour = null return false }) const controller = await freshController() @@ -656,11 +731,16 @@ describe('useFirstRunTourController', () => { const starting = controller.beginTour('image_z_image_turbo') await vi.advanceTimersByTimeAsync(INTRO_PREVIEW_MS) await starting + await nextTick() expect( - controller.tourWasShown.value, + controller.tourWasCompleted.value, 'a tour that resolved no steps made nothing for the nudge to celebrate' ).toBe(false) + expect( + controller.nudgeArmed.value, + 'a user who saw no tour is the one who most needs somewhere to go next' + ).toBe(true) }) it('stops offering the nudge once it is waved away', async () => { diff --git a/src/renderer/extensions/firstRunTour/tour/useFirstRunTourController.ts b/src/renderer/extensions/firstRunTour/tour/useFirstRunTourController.ts index ff4a0fe02aa..36cd1fda129 100644 --- a/src/renderer/extensions/firstRunTour/tour/useFirstRunTourController.ts +++ b/src/renderer/extensions/firstRunTour/tour/useFirstRunTourController.ts @@ -43,8 +43,8 @@ function useFirstRunTourControllerInternal() { const desktopLayout = useBreakpoints(breakpointsTailwind).greaterOrEqual('md') const tourWorkflow = shallowRef(null) const nudgeArmed = ref(false) - /** A tour that never appeared leaves the user nothing to be congratulated for. */ - const tourWasShown = ref(false) + /** Only a tour walked to the end made a first result to be congratulated for. */ + const tourWasCompleted = ref(false) // The tour's node ids are graph-local, so they only describe the workflow it // resolved against: swapping workflows leaves it pointing at strangers. @@ -125,6 +125,11 @@ function useFirstRunTourControllerInternal() { () => engine.activeTour === 'firstRun', (active) => { if (active) return + // Every ending leaves the user somewhere to go next, so every ending arms + // the nudge; only what it says depends on how the tour ended. + const ending = engine.lastEnding + tourWasCompleted.value = + ending?.tour === 'firstRun' && ending.outcome === 'completed' nudgeArmed.value = true stopOfflineGrace() releaseFirstRunTargets() @@ -147,7 +152,6 @@ function useFirstRunTourControllerInternal() { tourWorkflow.value = workflowStore.activeWorkflow ?? null runState.value = 'idle' nudgeArmed.value = false - tourWasShown.value = false registerTour( 'firstRun', () => firstRunTourSteps(templateId, runState), @@ -155,7 +159,6 @@ function useFirstRunTourControllerInternal() { ) await delay(INTRO_PREVIEW_MS) const started = await engine.startTour('firstRun') - tourWasShown.value = started if (!started) { releaseFirstRunTargets() tourWorkflow.value = null @@ -168,7 +171,7 @@ function useFirstRunTourControllerInternal() { return { beginTour, nudgeArmed: readonly(nudgeArmed), - tourWasShown: readonly(tourWasShown), + tourWasCompleted: readonly(tourWasCompleted), dismissNudge } }