: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 tk from 'timekeeper'
import { dayjs } from 'lib/dayjs'
import {
alignResolvedDateRangeToInterval,
formatDateTimeRange,
formatLocalizedDate,
formatLocalizedTime,
getConstrainedWeekRange,
getFormattedLastWeekDate,
parseDateInTimezone,
} from 'lib/utils/datetime'
describe('datetime utils', () => {
describe('getFormattedLastWeekDate()', () => {
it('happy case', () => {
tk.freeze(new Date(1330688329321))
expect(getFormattedLastWeekDate()).toEqual('January 13 - March 2, 2012')
tk.reset()
})
})
describe('formatDateTimeRange()', () => {
beforeEach(() => {
tk.freeze(new Date('2025-03-15T12:00:00.000Z'))
})
afterEach(() => {
tk.reset()
})
it('formats range in different years with full details', () => {
const from = dayjs('2024-12-31T14:30:45')
const to = dayjs('2025-01-01T16:45:30')
expect(formatDateTimeRange(from, to)).toEqual('December 31, 2024 14:30:45 - January 1, 2025 16:45:30')
})
it('formats range in same year but different days', () => {
const from = dayjs('2024-06-15T09:00:00')
const to = dayjs('2024-06-20T17:30:00')
expect(formatDateTimeRange(from, to)).toEqual('June 15, 2024 09:00 - June 20, 17:30')
})
it('hides time if both times are midnight', () => {
const from = dayjs('2024-06-15T00:00:00')
const to = dayjs('2024-06-20T00:00:00')
expect(formatDateTimeRange(from, to)).toEqual('June 15, 2024 - June 20')
})
it('formats range in same year as current year', () => {
const from = dayjs('2025-01-10T10:15:00')
const to = dayjs('2025-02-05T14:20:00')
expect(formatDateTimeRange(from, to)).toEqual('January 10, 10:15 - February 5, 14:20')
})
it('formats range on same day in different year', () => {
const from = dayjs('2024-08-10T09:30:00')
const to = dayjs('2024-08-10T18:45:00')
expect(formatDateTimeRange(from, to)).toEqual('August 10, 2024 09:30 - 18:45')
})
it('formats range on same day in current year', () => {
const from = dayjs('2025-03-15T08:00:00')
const to = dayjs('2025-03-15T20:00:00')
expect(formatDateTimeRange(from, to)).toEqual('08:00 - 20:00')
})
it('removes seconds when both times have zero seconds on same day', () => {
const from = dayjs('2025-03-15T10:30:00')
const to = dayjs('2025-03-15T14:45:00')
expect(formatDateTimeRange(from, to)).toEqual('10:30 - 14:45')
})
it('includes seconds when start time has non-zero seconds', () => {
const from = dayjs('2025-03-15T10:30:15')
const to = dayjs('2025-03-15T14:45:00')
expect(formatDateTimeRange(from, to)).toEqual('10:30:15 - 14:45:00')
})
it('includes seconds when end time has non-zero seconds', () => {
const from = dayjs('2025-03-15T10:30:00')
const to = dayjs('2025-03-15T14:45:30')
expect(formatDateTimeRange(from, to)).toEqual('10:30:00 - 14:45:30')
})
it('includes seconds when both times have non-zero seconds', () => {
const from = dayjs('2025-03-15T10:30:15')
const to = dayjs('2025-03-15T14:45:30')
expect(formatDateTimeRange(from, to)).toEqual('10:30:15 - 14:45:30')
})
it('handles range spanning different days in current year', () => {
const from = dayjs('2025-03-14T22:00:00')
const to = dayjs('2025-03-16T02:00:00')
expect(formatDateTimeRange(from, to)).toEqual('March 14, 22:00 - March 16, 02:00')
})
it('handles very short time ranges on same day', () => {
const from = dayjs('2025-03-15T12:00:00')
const to = dayjs('2025-03-15T12:01:00')
expect(formatDateTimeRange(from, to)).toEqual('12:00 - 12:01')
})
})
describe('getConstrainedWeekRange', () => {
beforeEach(() => {
// Reset locale to default before each test
dayjs.updateLocale('en', {
weekStart: 0,
})
})
describe('basic functionality', () => {
it('should return week boundaries for a mid-week date with Sunday start', () => {
const referenceDate = dayjs('2024-01-10') // Wednesday
const result = getConstrainedWeekRange(referenceDate)
expect(result.start.format('YYYY-MM-DD')).toBe('2024-01-07') // Sunday
expect(result.end.format('YYYY-MM-DD')).toBe('2024-01-13') // Saturday
})
it('should return week boundaries for a mid-week date with Monday start', () => {
const referenceDate = dayjs('2024-01-10') // Wednesday
const result = getConstrainedWeekRange(referenceDate, null, 1)
expect(result.start.format('YYYY-MM-DD')).toBe('2024-01-08') // Monday
expect(result.end.format('YYYY-MM-DD')).toBe('2024-01-14') // Sunday
})
it('should handle reference date at start of week', () => {
const referenceDate = dayjs('2024-01-07') // Sunday
const result = getConstrainedWeekRange(referenceDate, null, 0)
expect(result.start.format('YYYY-MM-DD')).toBe('2024-01-07') // Sunday
expect(result.end.format('YYYY-MM-DD')).toBe('2024-01-13') // Saturday
})
it('should handle reference date at end of week', () => {
const referenceDate = dayjs('2024-01-13') // Saturday
const result = getConstrainedWeekRange(referenceDate, null, 0)
expect(result.start.format('YYYY-MM-DD')).toBe('2024-01-07') // Sunday
expect(result.end.format('YYYY-MM-DD')).toBe('2024-01-13') // Saturday
})
})
describe('edge case handling', () => {
it('should handle Sunday reference date with Monday week start', () => {
const referenceDate = dayjs('2024-01-07') // Sunday
const result = getConstrainedWeekRange(referenceDate, null, 1)
// Sunday should be adjusted to Monday when week starts on Monday
expect(result.start.format('YYYY-MM-DD')).toBe('2024-01-08') // Monday
expect(result.end.format('YYYY-MM-DD')).toBe('2024-01-14') // Sunday
})
it('should handle Monday reference date with Sunday week start', () => {
const referenceDate = dayjs('2024-01-08') // Monday
const result = getConstrainedWeekRange(referenceDate, null, 0)
// Monday should be adjusted to Sunday when week starts on Sunday
expect(result.start.format('YYYY-MM-DD')).toBe('2024-01-07') // Sunday
expect(result.end.format('YYYY-MM-DD')).toBe('2024-01-13') // Saturday
})
it('should prevent weekEnd from being before weekStart', () => {
// This test simulates the edge case where dayjs locale manipulation
// could cause weekEnd to be calculated before weekStart
const referenceDate = dayjs('2024-01-01') // Monday, New Year's Day
const result = getConstrainedWeekRange(referenceDate, null, 1)
expect(result.start.isSameOrBefore(result.end)).toBe(true)
})
it('should handle year boundary dates', () => {
const referenceDate = dayjs('2023-12-31') // Sunday, New Year's Eve
const result = getConstrainedWeekRange(referenceDate, null, 0)
expect(result.start.format('YYYY-MM-DD')).toBe('2023-12-31') // Sunday
expect(result.end.format('YYYY-MM-DD')).toBe('2024-01-06') // Saturday
})
})
describe('date range boundary constraints', () => {
it('should constrain start date when boundary start is within week', () => {
const referenceDate = dayjs('2024-01-10') // Wednesday
const dateRangeBoundary = {
start: dayjs('2024-01-09'), // Tuesday
end: dayjs('2024-01-20'),
}
const result = getConstrainedWeekRange(referenceDate, dateRangeBoundary)
expect(result.start.format('YYYY-MM-DD')).toBe('2024-01-09') // Tuesday (constrained)
expect(result.end.format('YYYY-MM-DD')).toBe('2024-01-13') // Saturday (week end)
})
it('should constrain end date when boundary end is within week', () => {
const referenceDate = dayjs('2024-01-10') // Wednesday
const dateRangeBoundary = {
start: dayjs('2024-01-01'),
end: dayjs('2024-01-12'), // Friday
}
const result = getConstrainedWeekRange(referenceDate, dateRangeBoundary)
expect(result.start.format('YYYY-MM-DD')).toBe('2024-01-07') // Sunday (week start)
expect(result.end.format('YYYY-MM-DD')).toBe('2024-01-12') // Friday (constrained)
})
it('should constrain both start and end when boundary is within week', () => {
const referenceDate = dayjs('2024-01-10') // Wednesday
const dateRangeBoundary = {
start: dayjs('2024-01-09'), // Tuesday
end: dayjs('2024-01-11'), // Thursday
}
const result = getConstrainedWeekRange(referenceDate, dateRangeBoundary)
expect(result.start.format('YYYY-MM-DD')).toBe('2024-01-09') // Tuesday (constrained)
expect(result.end.format('YYYY-MM-DD')).toBe('2024-01-11') // Thursday (constrained)
})
it('should use week boundaries when date range is outside week', () => {
const referenceDate = dayjs('2024-01-10') // Wednesday
const dateRangeBoundary = {
start: dayjs('2024-01-01'),
end: dayjs('2024-01-31'),
}
const result = getConstrainedWeekRange(referenceDate, dateRangeBoundary)
expect(result.start.format('YYYY-MM-DD')).toBe('2024-01-07') // Sunday (week start)
expect(result.end.format('YYYY-MM-DD')).toBe('2024-01-13') // Saturday (week end)
})
it('should handle null date range boundary', () => {
const referenceDate = dayjs('2024-01-10') // Wednesday
const result = getConstrainedWeekRange(referenceDate, null)
expect(result.start.format('YYYY-MM-DD')).toBe('2024-01-07') // Sunday
expect(result.end.format('YYYY-MM-DD')).toBe('2024-01-13') // Saturday
})
it('should handle undefined date range boundary', () => {
const referenceDate = dayjs('2024-01-10') // Wednesday
const result = getConstrainedWeekRange(referenceDate)
expect(result.start.format('YYYY-MM-DD')).toBe('2024-01-07') // Sunday
expect(result.end.format('YYYY-MM-DD')).toBe('2024-01-13') // Saturday
})
it('should handle invalid date range boundary', () => {
const referenceDate = dayjs('2024-01-10') // Wednesday
const dateRangeBoundary = {
start: dayjs('invalid'),
end: dayjs('also-invalid'),
}
const result = getConstrainedWeekRange(referenceDate, dateRangeBoundary)
expect(result.start.format('YYYY-MM-DD')).toBe('2024-01-07') // Sunday
expect(result.end.format('YYYY-MM-DD')).toBe('2024-01-13') // Saturday
})
})
describe('week start day variations', () => {
it('should handle different week start days correctly', () => {
const referenceDate = dayjs('2024-01-10') // Wednesday
// Sunday start (default)
const sundayResult = getConstrainedWeekRange(referenceDate, null, 0)
expect(sundayResult.start.format('YYYY-MM-DD')).toBe('2024-01-07') // Sunday
expect(sundayResult.end.format('YYYY-MM-DD')).toBe('2024-01-13') // Saturday
// Monday start
const mondayResult = getConstrainedWeekRange(referenceDate, null, 1)
expect(mondayResult.start.format('YYYY-MM-DD')).toBe('2024-01-08') // Monday
expect(mondayResult.end.format('YYYY-MM-DD')).toBe('2024-01-14') // Sunday
})
it('should handle cached reference date adjustment', () => {
// Simulate a cached Sunday reference date when week start changes to Monday
const sundayReference = dayjs('2024-01-07') // Sunday
const result = getConstrainedWeekRange(sundayReference, null, 1)
// Should adjust Sunday to Monday
expect(result.start.format('YYYY-MM-DD')).toBe('2024-01-08') // Monday
expect(result.end.format('YYYY-MM-DD')).toBe('2024-01-14') // Sunday
})
it('should handle cached reference date adjustment for Monday to Sunday', () => {
// Simulate a cached Monday reference date when week start changes to Sunday
const mondayReference = dayjs('2024-01-08') // Monday
const result = getConstrainedWeekRange(mondayReference, null, 0)
// Should adjust Monday to Sunday
expect(result.start.format('YYYY-MM-DD')).toBe('2024-01-07') // Sunday
expect(result.end.format('YYYY-MM-DD')).toBe('2024-01-13') // Saturday
})
it('should handle cached reference date adjustment with out of bounds date range', () => {
// Simulate a cached Monday reference date when week start changes to Sunday
const mondayReference = dayjs('2025-06-02') // Monday
const dateRangeBoundary = {
// In the cached data, the date range is from the Monday of the week, which makes the reference within bounds if the week starts on Monday
// But if the week starts on Sunday, it will be out of bounds (will be on the previous week)
start: dayjs('2025-06-09'),
end: dayjs('2025-06-11'),
}
const result = getConstrainedWeekRange(mondayReference, dateRangeBoundary, 0)
// Should ignore the boundary and return the week starting from the previous Sunday
expect(result.start.format('YYYY-MM-DD')).toBe('2025-06-01') // Sunday of previous week
expect(result.end.format('YYYY-MM-DD')).toBe('2025-06-07') // Saturday of previous week
})
})
describe('return value validation', () => {
it('should always return valid dayjs objects', () => {
const referenceDate = dayjs('2024-01-10')
const result = getConstrainedWeekRange(referenceDate)
expect(result.start.isValid()).toBe(true)
expect(result.end.isValid()).toBe(true)
})
it('should ensure end is not before start', () => {
const referenceDate = dayjs('2024-01-10')
const result = getConstrainedWeekRange(referenceDate)
expect(result.start.isSameOrBefore(result.end)).toBe(true)
})
it('should return objects with correct structure', () => {
const referenceDate = dayjs('2024-01-10')
const result = getConstrainedWeekRange(referenceDate)
expect(result).toHaveProperty('start')
expect(result).toHaveProperty('end')
expect(typeof result.start.format).toBe('function')
expect(typeof result.end.format).toBe('function')
})
})
})
describe('formatLocalizedDate', () => {
const originalLanguage = Object.getOwnPropertyDescriptor(window.navigator, 'language')
const originalLang = document.documentElement.lang
afterEach(() => {
if (originalLanguage) {
Object.defineProperty(window.navigator, 'language', originalLanguage)
}
document.documentElement.lang = originalLang
})
it('should return US date format for en-US locale', () => {
Object.defineProperty(window.navigator, 'language', { value: 'en-US', configurable: true })
expect(formatLocalizedDate()).toBe('MMM DD')
})
it('should return US date format for en-CA locale', () => {
Object.defineProperty(window.navigator, 'language', { value: 'en-CA', configurable: true })
expect(formatLocalizedDate()).toBe('MMM DD')
})
it('should return international date format for en-GB locale', () => {
Object.defineProperty(window.navigator, 'language', { value: 'en-GB', configurable: true })
expect(formatLocalizedDate()).toBe('DD MMM')
})
it('should handle locale with region suffix', () => {
Object.defineProperty(window.navigator, 'language', { value: 'en-US-x-custom', configurable: true })
expect(formatLocalizedDate()).toBe('MMM DD')
})
it('should handle locale without region (defaults to international format)', () => {
Object.defineProperty(window.navigator, 'language', { value: 'en', configurable: true })
expect(formatLocalizedDate()).toBe('DD MMM')
})
it('should fall back to document.documentElement.lang when navigator.language is undefined', () => {
Object.defineProperty(window.navigator, 'language', { value: undefined, configurable: true })
document.documentElement.lang = 'en-GB'
expect(formatLocalizedDate()).toBe('DD MMM')
})
})
describe('formatLocalizedTime', () => {
const originalLanguage = Object.getOwnPropertyDescriptor(window.navigator, 'language')
const originalLang = document.documentElement.lang
const setLanguage = (value: string | undefined): void => {
Object.defineProperty(window.navigator, 'language', { value, configurable: true })
}
afterEach(() => {
if (originalLanguage) {
Object.defineProperty(window.navigator, 'language', originalLanguage)
}
document.documentElement.lang = originalLang
})
it.each([
['en-US', 'h:mm:ss A'],
['en-AU', 'h:mm:ss A'],
['en-GB', 'HH:mm:ss'],
['de-DE', 'HH:mm:ss'],
['fr-FR', 'HH:mm:ss'],
])('returns the hour cycle of the %s locale', (language, expected) => {
setLanguage(language)
expect(formatLocalizedTime()).toBe(expected)
})
it('falls back to document.documentElement.lang when navigator.language is undefined', () => {
setLanguage(undefined)
// a 24-hour locale, so the assertion still fails if the fallback resolves to the en-US default
document.documentElement.lang = 'de-CH'
expect(formatLocalizedTime()).toBe('HH:mm:ss')
})
it('falls back to 24-hour rather than throwing on a malformed language tag', () => {
setLanguage('not a language tag')
expect(formatLocalizedTime()).toBe('HH:mm:ss')
})
})
describe('alignResolvedDateRangeToInterval', () => {
it('returns undefined when resolvedDateRange is missing', () => {
expect(alignResolvedDateRangeToInterval(undefined, 'month')).toBeUndefined()
expect(alignResolvedDateRangeToInterval(null, 'month')).toBeUndefined()
})
it('returns undefined when date_from is empty', () => {
expect(
alignResolvedDateRangeToInterval({ date_from: '', date_to: '2026-04-07T23:59:59+00:00' }, 'month')
).toBeUndefined()
})
it.each([['day' as const], [null], [undefined]])(
'returns the range unchanged when interval is %s',
(interval) => {
const range = {
date_from: '2025-04-07T00:00:00+00:00',
date_to: '2026-04-07T23:59:59+00:00',
}
expect(alignResolvedDateRangeToInterval(range, interval)).toBe(range)
}
)
it('expands to full months when grouping by month', () => {
expect(
alignResolvedDateRangeToInterval(
{
date_from: '2025-04-07T00:00:00+00:00',
date_to: '2026-04-07T23:59:59+00:00',
},
'month'
)
).toEqual({
date_from: '2025-04-01T00:00:00+00:00',
date_to: '2026-04-30T23:59:59+00:00',
})
})
it.each([
['quarter' as const, '2025-04-01T00:00:00+00:00', '2026-06-30T23:59:59+00:00'],
['year' as const, '2025-01-01T00:00:00+00:00', '2026-12-31T23:59:59+00:00'],
])('expands to full periods when grouping by %s', (interval, expectedFrom, expectedTo) => {
expect(
alignResolvedDateRangeToInterval(
{
date_from: '2025-04-07T00:00:00+00:00',
date_to: '2026-04-07T23:59:59+00:00',
},
interval
)
).toEqual({
date_from: expectedFrom,
date_to: expectedTo,
})
})
it('preserves a non-UTC timezone offset', () => {
expect(
alignResolvedDateRangeToInterval(
{
date_from: '2025-04-07T00:00:00-08:00',
date_to: '2026-04-07T23:59:59-08:00',
},
'month'
)
).toEqual({
date_from: '2025-04-01T00:00:00-08:00',
date_to: '2026-04-30T23:59:59-08:00',
})
})
it('normalizes a Z suffix to +00:00', () => {
expect(
alignResolvedDateRangeToInterval(
{
date_from: '2025-04-07T00:00:00Z',
date_to: '2026-04-07T23:59:59Z',
},
'month'
)
).toEqual({
date_from: '2025-04-01T00:00:00+00:00',
date_to: '2026-04-30T23:59:59+00:00',
})
})
it('handles an ISO string with no timezone suffix', () => {
expect(
alignResolvedDateRangeToInterval(
{
date_from: '2025-04-07T00:00:00',
date_to: '2026-04-07T23:59:59',
},
'month'
)
).toEqual({
date_from: '2025-04-01T00:00:00',
date_to: '2026-04-30T23:59:59',
})
})
})
describe('parseDateInTimezone', () => {
describe('date-only strings', () => {
it.each([
['UTC', '+00:00'],
['America/Los_Angeles', '-07:00'],
['Asia/Tokyo', '+09:00'],
['Europe/Berlin', '+02:00'],
])('treats "2026-05-05" as wall-clock midnight in project tz %s', (timezone, expectedOffset) => {
const out = parseDateInTimezone('2026-05-05', timezone)
expect(out.format('YYYY-MM-DD HH:mm Z')).toEqual(`2026-05-05 00:00 ${expectedOffset}`)
})
it('returns the same calendar day across browser timezones (no DST drift)', () => {
// The chart x-axis renders this with a 'D MMM' or 'MMM D' format.
// Across DST boundaries and across browser timezones, the calendar day
// for a date-only string must not shift by ±1 day.
const out = parseDateInTimezone('2026-03-08', 'America/Los_Angeles')
expect(out.format('D MMM YYYY')).toEqual('8 Mar 2026')
})
})
describe('strings with explicit timezone offset', () => {
it('treats Z-suffixed timestamps as real instants and converts to project tz', () => {
// 2024-04-28 23:30 UTC = 2024-04-29 08:30 in Tokyo.
const out = parseDateInTimezone('2024-04-28T23:30:00Z', 'Asia/Tokyo')
expect(out.format('YYYY-MM-DD HH:mm Z')).toEqual('2024-04-29 08:30 +09:00')
})
it('treats +HH:MM offsets as real instants', () => {
// 2024-04-28 00:00 -07:00 = 2024-04-28 07:00 UTC = 2024-04-28 16:00 Tokyo.
const out = parseDateInTimezone('2024-04-28T00:00:00-07:00', 'Asia/Tokyo')
expect(out.format('YYYY-MM-DD HH:mm Z')).toEqual('2024-04-28 16:00 +09:00')
})
})
describe('invalid inputs', () => {
it('returns an invalid Dayjs for unparseable strings instead of throwing', () => {
const out = parseDateInTimezone('not-a-date', 'UTC')
expect(dayjs.isDayjs(out)).toBe(true)
expect(out.isValid()).toBe(false)
})
})
})
})