Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
98 changes: 98 additions & 0 deletions src/platform/onboarding/onboardingTourStore.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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()
Expand Down
23 changes: 23 additions & 0 deletions src/platform/onboarding/onboardingTourStore.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -51,6 +65,7 @@ export const useOnboardingTourStore = defineStore('onboardingTour', () => {
const telemetry = useTelemetry()

const state = shallowRef<TourState>(IDLE)
const lastEnding = shallowRef<TourEnding | null>(null)
let stepController: AbortController | null = null
let lastRun = 0

Expand Down Expand Up @@ -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,
Expand Down Expand Up @@ -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) {
Expand Down Expand Up @@ -373,6 +395,7 @@ export const useOnboardingTourStore = defineStore('onboardingTour', () => {

return {
activeTour: readonly(activeTour),
lastEnding: readonly(lastEnding),
step,
isLast,
canGoBack,
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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<string[]>([]),
dismissNudge: vi.fn(() => {
mocks.nudgeArmed.value = false
Expand All @@ -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
})
}))
Expand Down Expand Up @@ -71,6 +71,7 @@ describe('FirstRunTourNudge', () => {
vi.clearAllMocks()
vi.useFakeTimers()
mocks.nudgeArmed.value = false
mocks.tourWasCompleted.value = true
mocks.openDialogs.value = []
})

Expand Down Expand Up @@ -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
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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' }
Expand All @@ -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(),
Expand Down Expand Up @@ -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,
Expand Down Expand Up @@ -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
})
Expand Down Expand Up @@ -644,23 +678,69 @@ 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()

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 () => {
Expand Down
Loading
Loading