fix(#324): runs xpath tests with the same timezone

[latin-panda]

Closes #324

I have verified this PR works in these browsers (latest versions):

• Chrome
• Firefox
• Safari (macOS)
• Safari (iOS)
• Not applicable

What else has been done to verify this works as intended?

To reproduce the error:

1. Change the machine time to March 1st at 23:30 Los Angeles timezone
2. Run the test suite yarn workspace @getodk/xpath test
3. See the tests failing like this:

Other things done:

After implementing the fix, I tried setting my machine in different timezones, ran the tests, and they passed. The different timezones have been passed to the "now" function correctly.

The offset is being appended to the localDateTimeString

I tried making a test about DST, but it's hard to trick reliably the test to take a different DST of the same timezone. However, I added some debugging code in localDateTimeString function, and I can see the offset switching to/from DST for the same timezone.

// The process.env.TZ value is America/New_York
// Current date is March 3rd

console.log(dateTime.offset); // Prints "-05:00"
const dstDate = Temporal.ZonedDateTime.from("2025-07-01T23:30:00[America/New_York]");
console.log(dstDate.offset); // Prints "-04:00"

Why is this the best possible solution? Were any other approaches considered?

This ensures the tests are run in the same timezone by setting it in the beforeEach hook using the useFakeTimers utility. However, this doesn't mock the DST, which has been challenging to tick the system timer.

How does this change affect users? Describe intentional changes to behavior and behavior that could have accidentally been affected by code changes. In other words, what are the regression risks?

N/A

Do we need any specific form for testing your changes? If so, please attach one.

I don't think so

What's changed

• Adds a global beforeEach and AfterEach hook to set the tests' timezone
• Adds a new optional environment variable for the tests' locale

[changeset-bot]

⚠️ No Changeset found

Latest commit: 4ae1011

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[latin-panda]

I didn't find the usage of this IMPLEMENTATION. I wanted to add a JSDoc description.

[latin-panda]

It was added in this commit . It's unclear what it is for. I'll leave it there for now and ask Trevor later

[latin-panda]

@eyelidlessness When you have a chance, can you please review it? Thank you!

[latin-panda]

This was added for completeness and to clarify that the tests expect the date format in this locale.
When switching to another locale (e.g., es-AR or es-MX), some tests fail because they expect a different date format.

With es-MX the now() returns a 1-1-1970 date, and tests using today() fail.
With es-AR the now() returns the current date correctly. But other tests fails, where tomorrow is set in en-US standard 2025-03-05

 FAIL  test/xforms/date-comparison.test.ts > date comparison > tomorrow > should be greater than or equal to today()
AssertionError: expected false to deeply equal true

- Expected
+ Received

- true
+ false

[lognaturel]

Was the root cause of #324 then that the test was written with the assumption that the timezone was Arizona time and because that wasn't set uniformly the device time was being used in some cases?

[latin-panda]

Was the root cause of #324 then that the test was written with the assumption that the timezone was Arizona time, and because that wasn't set uniformly the device time was being used in some cases?

@lognaturel, yes, that's what I understand.

The default timezone (Arizona) was added in this commit, with this JSDoc

TODO: Many integration tests concerned with datetimes currently expect a
fixed time zone, for hard-coded values. The time zone was also chosen
specifically because it does not (er, did not then, nor does presently at
time of writing) observe daylight saving time or any other periodic
change in its UTC offset.

This PR ensures the timezone is applied to all tests by introducing a global beforeEach hook and instructs the test runner to use a fake timezone (default to Arizona) and fake locale (default to en-US). These are reverted to use real machine timezone and locale in a global afterEach hook.

[lognaturel]

I think this comment wasn't related to the issue here but was a tongue and cheek remark about how it's possible for new Date(); to be run milliseconds before midnight and then the now() function to be evaluated milliseconds after midnight in which case the test would fail even if the code is all correct. I do agree with removing the comment.

[latin-panda]

Thanks for the explanation! I didn't interpret it like that, but it makes sense.

[lognaturel]

This was intended/expected to set the global timezone for tests, does that sound right? Is the issue then that this doesn't work or at least not consistently? Is some of what's at vitest-dev/vitest#1575 (comment) related?

If there was an attempted alternative approach to set a consistent timezone that didn't work, I think it'd be helpful to remove it so there isn't ambiguity about the source of truth.

[latin-panda]

Good question

The define option in the Vite config is for defining global constants that are replaced at build time or made available as globals during development. The test runner doesn't automatically set the timezone by defining the TZ constant.

We still need the constant to setup the xpath's evaluator option and to get the default locale for mocking the timezone and locale in the global beforeEach

[latin-panda]

ref: https://vite.dev/config/shared-options.html#define

[lognaturel]

Thanks for the explanation! I'm not super familiar with these test options. So now I'm seeing that the evaluator timezone was being set but there was nothing previously setting the vitest timezone. From what I've read, using a global beforeEach seems like a good approach to do that.

[latin-panda]

Thanks for the explanation! I'm not super familiar with these test options.

No worries, I'm also learning as I fix this bug