:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.
Python ab-testingai-analyticsanalyticscdpdata-warehouseexperimentsfeature-flagsjavascriptproduct-analyticspythonreactsession-replaysurveystypescriptweb-analytics
import '@testing-library/jest-dom'
import { act, fireEvent, render } from '@testing-library/react'
import { BindLogic, Provider } from 'kea'
import posthog from 'posthog-js'
import { SessionPlayerState } from '~/types'
import { setupSessionRecordingTest } from './__mocks__/test-setup'
import { PlayerFrame } from './PlayerFrame'
import { PlayerFrameOverlay } from './PlayerFrameOverlay'
import { sessionRecordingPlayerLogic } from './sessionRecordingPlayerLogic'
describe('PlayerFrame', () => {
const logicProps = { sessionRecordingId: '1', playerKey: 'player-frame-test' }
beforeEach(() => {
setupSessionRecordingTest()
})
// Each retry renders a new frame element, so a test looks the frame up again after each one.
function currentFrame(container: HTMLElement): HTMLIFrameElement {
const iframe = container.querySelector('iframe.PlayerFrame__document')
if (!(iframe instanceof HTMLIFrameElement)) {
throw new Error('the player did not render its frame')
}
// jsdom leaves the frame document mid-load, and the player judges a document that finished loading.
Object.defineProperty(iframe.contentDocument!, 'readyState', { value: 'complete', configurable: true })
return iframe
}
function renderPlayerFrame(): HTMLIFrameElement {
const { container } = render(
<Provider>
<BindLogic logic={sessionRecordingPlayerLogic} props={logicProps}>
<PlayerFrame />
</BindLogic>
</Provider>
)
return currentFrame(container)
}
it('mounts the player on the frame document once the frame loads', () => {
const captureSpy = jest.spyOn(posthog, 'capture')
const iframe = renderPlayerFrame()
const frameDocument = iframe.contentDocument!
frameDocument.open()
frameDocument.write('<div id="player-frame-content"></div>')
frameDocument.close()
fireEvent.load(iframe)
expect(sessionRecordingPlayerLogic(logicProps).values.rootFrame).toBe(
frameDocument.getElementById('player-frame-content')
)
// The frame is same-origin, so any script permission added here runs as the app.
expect(iframe).toHaveAttribute('sandbox', 'allow-same-origin')
expect(captureSpy).not.toHaveBeenCalledWith('replay player frame load recovered', expect.anything())
})
// A load event that never arrives used to leave rrweb with nowhere to mount, so the player
// showed an empty rectangle for as long as the tab stayed open. The timeout feeds the same
// failure action as a load without a mount node, so the first timeout retries the frame and
// the retry flow reaches the player's error state.
it('retries the frame when the load event never arrives, then shows the player error', () => {
jest.useFakeTimers()
try {
const captureSpy = jest.spyOn(posthog, 'capture')
const captureExceptionSpy = jest.spyOn(posthog, 'captureException')
const iframe = renderPlayerFrame()
const container = iframe.parentElement!
// The load never fires. The 10s timeout reports the first failure, which schedules a retry.
act(() => {
jest.advanceTimersByTime(10000)
})
expect(captureSpy).toHaveBeenCalledWith(
'replay player frame load retried',
// The focus and activation that may decide the load are read when the frame mounted, not 10s later.
expect.objectContaining({
attempt: 1,
restarts: 0,
frameMountHasFocus: expect.any(Boolean),
msSinceFrameMount: 10000,
})
)
// The retry replaces the frame, because a frame stuck on about:blank can ignore a new src.
// The new frame's load also never fires. The frame gets MAX_PLAYER_FRAME_LOAD_RETRIES
// retries, so failures 1 and 2 retry and failure 3 reaches the error state.
act(() => {
jest.advanceTimersByTime(1000)
})
expect(currentFrame(container)).not.toBe(iframe)
expect(currentFrame(container)).toHaveAttribute('src', '/replay_player_frame/index.html?retry=1')
act(() => {
jest.advanceTimersByTime(10000)
})
expect(captureSpy).toHaveBeenCalledWith(
'replay player frame load retried',
expect.objectContaining({ attempt: 2 })
)
act(() => {
jest.advanceTimersByTime(2000)
})
expect(currentFrame(container)).toHaveAttribute('src', '/replay_player_frame/index.html?retry=2')
act(() => {
jest.advanceTimersByTime(10000)
})
expect(sessionRecordingPlayerLogic(logicProps).values.currentPlayerState).toBe(SessionPlayerState.ERROR)
expect(captureExceptionSpy).toHaveBeenCalledTimes(1)
} finally {
jest.useRealTimers()
}
})
it.each([
{
state: 'no browsing context',
// jsdom gives a document made this way no browsing context, the same as a browser does.
frameDocument: (): Document => document.implementation.createHTMLDocument(),
report: { attempt: 1, frameUrlPath: null },
},
{
state: 'a read that throws',
frameDocument: (): Document => {
const frameDocument = document.implementation.createHTMLDocument()
Object.defineProperty(frameDocument, 'title', {
get: () => {
throw new Error('read failed')
},
})
return frameDocument
},
report: { attempt: 1, frameDocumentReadable: true },
},
])('retries the frame when the timed-out frame has $state', ({ frameDocument, report }) => {
jest.useFakeTimers()
try {
const captureSpy = jest.spyOn(posthog, 'capture')
const iframe = renderPlayerFrame()
const container = iframe.parentElement!
Object.defineProperty(iframe, 'contentDocument', { value: frameDocument(), configurable: true })
act(() => {
jest.advanceTimersByTime(10000)
})
expect(captureSpy).toHaveBeenCalledWith('replay player frame load retried', expect.objectContaining(report))
act(() => {
jest.advanceTimersByTime(1000)
})
expect(currentFrame(container)).toHaveAttribute('src', '/replay_player_frame/index.html?retry=1')
} finally {
jest.useRealTimers()
}
})
// Firefox fires load for the frame's initial about:blank document, and a load event for a previous
// document arrives while the shell is still parsing. Neither has a mount node, and neither is a failure.
it.each([
['the blank first document loads', 'about:blank', 'complete'],
['a load arrives while the shell is still parsing', '/replay_player_frame/index.html', 'loading'],
])('reports nothing when %s', (_, url, readyState) => {
const captureSpy = jest.spyOn(posthog, 'capture')
const captureExceptionSpy = jest.spyOn(posthog, 'captureException')
const iframe = renderPlayerFrame()
// jsdom does not load the frame's src, so its document already carries the shell URL.
Object.defineProperty(iframe.contentDocument!, 'URL', { value: url })
Object.defineProperty(iframe.contentDocument!, 'readyState', { value: readyState, configurable: true })
fireEvent.load(iframe)
expect(captureExceptionSpy).not.toHaveBeenCalled()
expect(captureSpy).not.toHaveBeenCalledWith('replay player frame load retried', expect.anything())
})
// A same-origin error page, a login redirect, or a browser network-error page all fire load
// with a document that has no mount node. The frame gets retried before the player shows its error
// state. Each retry records what the frame showed, and only the last failure is an exception.
it('retries a frame that loads without a mount node, then shows the player error', () => {
jest.useFakeTimers()
try {
const captureSpy = jest.spyOn(posthog, 'capture')
const captureExceptionSpy = jest.spyOn(posthog, 'captureException')
const container = renderPlayerFrame().parentElement!
const logic = sessionRecordingPlayerLogic(logicProps)
fireEvent.load(currentFrame(container))
act(() => {
jest.advanceTimersByTime(1000)
})
const retriedFrame = currentFrame(container)
expect(retriedFrame).toHaveAttribute('src', '/replay_player_frame/index.html?retry=1')
// A browser error page is cross-origin to the app, so the frame's document is unreadable.
Object.defineProperty(retriedFrame, 'contentDocument', { value: null, configurable: true })
fireEvent.load(retriedFrame)
act(() => {
jest.advanceTimersByTime(2000)
})
expect(currentFrame(container)).toHaveAttribute('src', '/replay_player_frame/index.html?retry=2')
expect(logic.values.currentPlayerState).not.toBe(SessionPlayerState.ERROR)
const lastFrame = currentFrame(container)
Object.defineProperty(lastFrame, 'contentDocument', { value: null, configurable: true })
fireEvent.load(lastFrame)
expect(logic.values.currentPlayerState).toBe(SessionPlayerState.ERROR)
expect(
captureSpy.mock.calls
.filter(([event]) => event === 'replay player frame load retried')
.map(([, properties]) => [properties?.attempt, properties?.frameDocumentReadable])
).toEqual([
[1, true],
[2, false],
])
expect(captureExceptionSpy).toHaveBeenCalledTimes(1)
expect(captureExceptionSpy.mock.calls[0][1]).toMatchObject({ attempt: 3, frameDocumentReadable: false })
} finally {
jest.useRealTimers()
}
})
// Comparing the frames that loaded after a failure with the ones that did not tests why a retry recovers.
it('reports a frame that loads after a failed load', () => {
jest.useFakeTimers()
try {
const captureSpy = jest.spyOn(posthog, 'capture')
const container = renderPlayerFrame().parentElement!
fireEvent.load(currentFrame(container))
act(() => {
jest.advanceTimersByTime(1000)
})
const frameDocument = currentFrame(container).contentDocument!
frameDocument.open()
frameDocument.write('<div id="player-frame-content"></div>')
frameDocument.close()
fireEvent.load(currentFrame(container))
expect(captureSpy).toHaveBeenCalledWith(
'replay player frame load recovered',
expect.objectContaining({ attempt: 1, restarts: 0, frameMountHasFocus: expect.any(Boolean) })
)
} finally {
jest.useRealTimers()
}
})
// A retry from the error card must load a new frame. A page reload repeats the same failed load.
it('loads a new frame and mounts the player when the viewer retries from the error state', () => {
const onLine = jest.spyOn(navigator, 'onLine', 'get').mockReturnValue(false)
try {
const captureSpy = jest.spyOn(posthog, 'capture')
const { container } = render(
<Provider>
<BindLogic logic={sessionRecordingPlayerLogic} props={logicProps}>
<PlayerFrame />
<PlayerFrameOverlay />
</BindLogic>
</Provider>
)
const logic = sessionRecordingPlayerLogic(logicProps)
const failedFrame = currentFrame(container)
fireEvent.load(failedFrame)
expect(logic.values.currentPlayerState).toBe(SessionPlayerState.ERROR)
onLine.mockReturnValue(true)
fireEvent.click(container.querySelector('[data-attr="replay-overlay-retry-player-frame"]')!)
expect(captureSpy).toHaveBeenCalledWith(
'replay player frame load restarted',
expect.objectContaining({ restarts: 1, browserOnline: true })
)
expect(logic.values.currentPlayerState).not.toBe(SessionPlayerState.ERROR)
expect(currentFrame(container)).not.toBe(failedFrame)
const frameDocument = currentFrame(container).contentDocument!
frameDocument.open()
frameDocument.write('<div id="player-frame-content"></div>')
frameDocument.close()
fireEvent.load(currentFrame(container))
expect(logic.values.rootFrame).toBe(frameDocument.getElementById('player-frame-content'))
} finally {
onLine.mockRestore()
}
})
// The failure count starts again after a restart, so only the restart count tells these reports apart
// from the first round of automatic retries.
it('reports the restart count with a frame failure after the viewer retries', () => {
const onLine = jest.spyOn(navigator, 'onLine', 'get').mockReturnValue(false)
try {
const captureSpy = jest.spyOn(posthog, 'capture')
const container = renderPlayerFrame().parentElement!
const logic = sessionRecordingPlayerLogic(logicProps)
fireEvent.load(currentFrame(container))
expect(logic.values.currentPlayerState).toBe(SessionPlayerState.ERROR)
onLine.mockReturnValue(true)
act(() => logic.actions.restartPlayerFrameLoad())
fireEvent.load(currentFrame(container))
expect(captureSpy).toHaveBeenCalledWith(
'replay player frame load retried',
expect.objectContaining({ attempt: 1, restarts: 1 })
)
} finally {
onLine.mockRestore()
}
})
// A frame cannot load while the browser is offline, so the player shows its error at once instead of
// staying blank while it waits for a connection that may not come back.
it('shows the player error without a retry while the browser is offline', () => {
const onLine = jest.spyOn(navigator, 'onLine', 'get').mockReturnValue(false)
jest.useFakeTimers()
try {
const captureSpy = jest.spyOn(posthog, 'capture')
const captureExceptionSpy = jest.spyOn(posthog, 'captureException')
const iframe = renderPlayerFrame()
fireEvent.load(iframe)
act(() => {
jest.advanceTimersByTime(10000)
})
expect(sessionRecordingPlayerLogic(logicProps).values.currentPlayerState).toBe(SessionPlayerState.ERROR)
expect(iframe).toHaveAttribute('src', '/replay_player_frame/index.html')
expect(captureSpy).not.toHaveBeenCalledWith('replay player frame load retried', expect.anything())
expect(captureExceptionSpy).toHaveBeenCalledTimes(1)
expect(captureExceptionSpy.mock.calls[0][1]).toMatchObject({ attempt: 1, browserOnline: false })
} finally {
jest.useRealTimers()
onLine.mockRestore()
}
})
})