Skip to content
46 changes: 46 additions & 0 deletions browser_tests/tests/agent/agentOnboarding.spec.ts
Original file line number Diff line number Diff line change
Expand Up @@ -52,6 +52,52 @@ test.describe('Agent onboarding tour', { tag: ['@cloud', '@ui'] }, () => {
.toBe('false')
})

test('points the first card at the highlighted panel and answers clicks on it', async ({
Comment thread
christian-byrne marked this conversation as resolved.
Resolved
page,
agentFlagEnabled
}) => {
await bootAgentApp(page, agentFlagEnabled, {
onboardingCompleted: false
})
await new AgentPanel(page).open()

const firstCard = page.getByRole('dialog', {
name: enMessages.agent.coachTitle
})
await expect(firstCard).toBeVisible()
const arrow = page.getByTestId('agent-coach-arrow')
const spotlight = page.getByTestId('agent-coach-spotlight')
await expect(arrow).toHaveCSS('visibility', 'visible')
await expect
.poll(async () => {
const [arrowBox, spotlightBox] = await Promise.all([
arrow.boundingBox(),
spotlight.boundingBox()
])
if (!arrowBox || !spotlightBox) return null
return {
leftOfSpotlight: arrowBox.x < spotlightBox.x,
centersAligned:
Math.abs(
arrowBox.y +
arrowBox.height / 2 -
(spotlightBox.y + spotlightBox.height / 2)
) < 4
}
})
.toEqual({ leftOfSpotlight: true, centersAligned: true })
Comment thread
christian-byrne marked this conversation as resolved.
Resolved

const spotlightBox = await spotlight.boundingBox()
if (!spotlightBox) throw new Error('spotlight has no box')
await page.mouse.click(
spotlightBox.x + spotlightBox.width / 2,
spotlightBox.y + spotlightBox.height / 2
)

await expect(firstCard).toBeFocused()
await expect(firstCard).toBeVisible()
})

test('replays the tour from the header after it has been completed', async ({
page,
agentFlagEnabled
Expand Down
9 changes: 9 additions & 0 deletions src/workbench/extensions/agent/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -140,6 +140,15 @@ panel, composer, graph and chat history. **Next** advances through the cards;
**Done** on the last card, **Skip** on any card and Escape once a card is on
screen all dismiss the tour and mark it complete.

A card placed beside its target carries an arrow pointing at it; cards placed
anywhere else never do. The arrow is also hidden when it would not actually
point at the target: when a narrow viewport has shifted the card onto its
target, or when the target's center lies outside the span the arrow can reach
along the card's edge. The rest of the
screen, the highlighted area included, does not respond while a card is up; a
click there briefly outlines the card and moves focus to it
so the user finds the controls instead of clicking the highlight.

Completion is device-local in `localStorage`, scoped to the authenticated user
and active workspace; with either unresolved there is no scope to record, so no
tour is shown at all. It does not sync through Global Settings. A different
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -51,6 +51,7 @@ const rectangles: Record<string, DOMRect> = {
history: new DOMRect(970, 104, 24, 24)
}
const tooltipRect = new DOMRect(998, 105, 84, 22)
const ARROW_SIZE = 12

function mount(steps = STEPS) {
return render(
Expand Down Expand Up @@ -79,6 +80,8 @@ beforeEach(() => {
vi.spyOn(HTMLElement.prototype, 'getBoundingClientRect').mockImplementation(
function (this: HTMLElement) {
if (this.getAttribute('role') === 'tooltip') return tooltipRect
if (this.dataset.testid === 'agent-coach-arrow')
return new DOMRect(0, 0, ARROW_SIZE, ARROW_SIZE)
return (
rectangles[this.id] ??
new DOMRect(
Expand Down Expand Up @@ -230,6 +233,136 @@ describe('OnboardingCoach', () => {
}
})

it.for(STEPS.filter((step) => step.placement !== 'graph-bottom'))(
'points the $placement card arrow at the middle of its target',
async (step) => {
mount([step])
const dialog = await screen.findByRole('dialog', { name: step.title })
const arrow = screen.getByTestId('agent-coach-arrow')
const targetRect = rectangles[step.target.slice(1)]

expect(dialog).toContainElement(arrow)
await waitFor(() =>
expect(
parseFloat(dialog.style.top) +
parseFloat(arrow.style.top) +
ARROW_SIZE / 2
).toBeCloseTo(targetRect.top + targetRect.height / 2, 0)
)
expect(arrow).not.toHaveStyle({ visibility: 'hidden' })
}
)

it('draws no arrow on the canvas card, which sits on its target', async () => {
mount([STEPS[2]])
await screen.findByRole('dialog', { name: STEPS[2].title })

expect(screen.queryByTestId('agent-coach-arrow')).toBeNull()
})

it('hides the arrow when the target center is outside the arrow reach', async () => {
const panel = rectangles.panel
rectangles.panel = new DOMRect(950, 0, 420, 24)
try {
mount([STEPS[0]])
const dialog = await screen.findByRole('dialog', {
name: STEPS[0].title
})
await waitFor(() => expect(dialog.style.opacity).toBe('1'))
expect(
parseFloat(dialog.style.left) + dialog.offsetWidth
).toBeLessThanOrEqual(rectangles.panel.left)
expect(screen.getByTestId('agent-coach-arrow')).toHaveStyle({
visibility: 'hidden'
})
} finally {
rectangles.panel = panel
}
})

it('keeps the arrow when a small shift still leaves a gap beside the target', async () => {
const panel = rectangles.panel
rectangles.panel = new DOMRect(330, 60, 420, 700)
try {
mount([STEPS[0]])
const dialog = await screen.findByRole('dialog', {
name: STEPS[0].title
})
await waitFor(() => expect(dialog.style.opacity).toBe('1'))
expect(parseFloat(dialog.style.left)).toBe(8)
Comment thread
christian-byrne marked this conversation as resolved.
Resolved
expect(screen.getByTestId('agent-coach-arrow')).not.toHaveStyle({
visibility: 'hidden'
})
} finally {
rectangles.panel = panel
}
})

it('draws attention to the card and focuses it when the user clicks the dimmed screen or the highlighted area', async () => {
const user = userEvent.setup()
mount()
const dialog = await screen.findByRole('dialog', { name: STEPS[0].title })
expect(dialog).not.toHaveAttribute('data-nudged')

await user.click(screen.getByTestId('agent-coach-scrim'))

expect(dialog).toHaveAttribute('data-nudged')
expect(dialog).toHaveFocus()
expect(screen.getByRole('dialog', { name: STEPS[0].title })).toBe(dialog)
expect(localStorage.getItem(KEY)).toBe('false')
expect(telemetry().trackAgentOnboardingStep).not.toHaveBeenCalled()
})

it('stops drawing attention to the card when the user moves to the next card', async () => {
const user = userEvent.setup()
mount()
await screen.findByRole('dialog', { name: STEPS[0].title })
await user.click(screen.getByTestId('agent-coach-scrim'))
await user.click(screen.getByRole('button', { name: 'Next' }))

const second = await screen.findByRole('dialog', { name: STEPS[1].title })
expect(second).not.toHaveAttribute('data-nudged')
})

it('hides the arrow when there is no room beside the target and the card overlaps it', async () => {
const panel = rectangles.panel
rectangles.panel = new DOMRect(100, 60, 1290, 700)
try {
mount([STEPS[0]])
const dialog = await screen.findByRole('dialog', {
name: STEPS[0].title
})
await waitFor(() => expect(dialog.style.opacity).toBe('1'))
expect(
parseFloat(dialog.style.left) + dialog.offsetWidth
).toBeGreaterThan(rectangles.panel.left)
expect(screen.getByTestId('agent-coach-arrow')).toHaveStyle({
visibility: 'hidden'
})
} finally {
rectangles.panel = panel
}
})
Comment thread
christian-byrne marked this conversation as resolved.
Resolved

it('stops drawing attention to the card shortly after the click', async () => {
vi.useFakeTimers()
try {
const user = userEvent.setup({ advanceTimers: vi.advanceTimersByTime })
mount()
const dialog = await screen.findByRole('dialog', {
name: STEPS[0].title
})
await user.click(screen.getByTestId('agent-coach-scrim'))
expect(dialog).toHaveAttribute('data-nudged')

await vi.advanceTimersByTimeAsync(2_000)

expect(dialog).not.toHaveAttribute('data-nudged')
} finally {
vi.useRealTimers()
}
})
Comment thread
christian-byrne marked this conversation as resolved.
Resolved

it('shows the target in its hover state with its tooltip inside the spotlight', async () => {
const user = userEvent.setup()
const steps = STEPS.map((step, index) =>
Expand Down
Loading
Loading