Merge pull request #3144 from obsidian-tasks-group/test-timezones-and-recurrence

vault: Add manual test of recurrence in Pacific/Auckland at DST boundary

Author: claremacrae

contributing/Testing/About Testing.md

@@ -23,6 +23,7 @@ Testing dates and times:
 
 - [[How do I use Moment in tests]] - how to test date and time values
 - [[Simulating Dates and Times]] - examples of how to use fixed dates and times in tests
+- [[Testing and Time Zones]] - how to test in different time zones (with difficulty)
 
 Testing code that uses Obsidian API:
 

contributing/Testing/Testing and Time Zones.md

@@ -0,0 +1,33 @@
+---
+publish: true
+---
+
+# Testing in different Time Zones
+
+<span class="related-pages">#testing/automated-testing #testing/manual-testing</span>
+
+## Fixing the time zone to UTC in Jest
+
+Currently, our Jest tests fix the time zone at run-time to `UTC` in [tests/global-setup.js](https://github.com/obsidian-tasks-group/obsidian-tasks/blob/main/tests/global-setup.js).
+
+This was done to ensure that the tests pass for contributors all around the world, regardless of their own time zone.
+
+## Why we don't use 'moment-timezone'
+
+... in `src/`:
+
+1. Obsidian plugins are instructed to use `moment` as supplied by Obsidian, to reduce plugin size.
+1. `moment-timezone` increases the Tasks plugin `main.js` size 10-fold, which would slow down start-up time.
+1. So we can't use `moment-timezone` in the released plugin.
+
+... in `tests/`:
+
+1. The only way to set the timezone dynamically in tests is to use [moment-timezone](https://momentjs.com/timezone/docs/).
+1. But `moment-timezone` modifies the behaviour of `moment`
+1. Which would invalidate any of tests of behaviour that uses `moment`: we could not be confident that the code would behave the same in the released plugin as it does in tests.
+
+## Manually testing in different time zones
+
+In the absence of automated testing of Tasks in different time zones, see this manual test in the 'Tasks-Demo' vault:
+
+- [Tasks-Demo/Manual Testing/Time Zones/Pacific-Auckland.md](https://github.com/obsidian-tasks-group/obsidian-tasks/blob/main/resources/sample_vaults/Tasks-Demo/Manual%20Testing/Time%20Zones/Pacific-Auckland.md).

resources/sample_vaults/Tasks-Demo/Manual Testing/Time Zones/Pacific-Auckland.md

@@ -0,0 +1,46 @@
+# Pacific-Auckland
+
+> [!NOTE]
+> These instructions assume testing on Mac - hence use of `open` to an Obsidian URL...
+
+## Setting up this manual test
+
+1. Make sure that you have opened the [Tasks-Demo](https://github.com/obsidian-tasks-group/obsidian-tasks/tree/main/resources/sample_vaults/Tasks-Demo) test vault previously, so that Obsidian knows where that vault is on your computer.
+2. Run the following command
+
+    ```bash
+    TZ=Pacific/Auckland open 'obsidian://open?vault=Tasks-Demo&file=Manual%20Testing%2FTime%20Zones%2FPacific-Auckland'
+    ```
+
+3. View this page in Reading or Live Preview mode
+4. Confirm that the headings in the Tasks block are:
+    - `Timezone: Pacific/Auckland`
+    - `2024-09-28 Saturday`
+
+## Run the test
+
+1. Complete the task in this file.
+2. Check that the due date of the new task - and the new heading - is '2024-09-28 Sunday'
+
+## Tasks Plugin Search
+
+```tasks
+not done
+path includes {{query.file.path}}
+
+group by function 'Timezone: ' + process.env.TZ
+group by due
+
+hide backlinks
+```
+
+## Test task
+
+- [ ] #task Next due date should be `2024-09-28 Sunday` 🔁 every day 📅 2024-09-28
+
+## Background
+
+- This manual test shows the existence of the bug logged in:
+  - [Completing a daily recurring task creates task set to same day [the day before Australian clocks switch to daylight savings]](https://github.com/obsidian-tasks-group/obsidian-tasks/issues/2309)
+- It was written to test the behaviour of pull request \#3121:
+  - [fix: advance recurring tasks correctly at start of Daylight Savings Time](https://github.com/obsidian-tasks-group/obsidian-tasks/pull/3121)

tests/global-setup.js

@@ -1,3 +1,12 @@
 module.exports = async () => {
     process.env.TZ = 'UTC';
+
+    /*
+     * Below is an example alternative time zone, for experimentation.
+     * See https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
+     * Note: Currently many tests fail if the timezone is changed, due to
+     *       the use of `moment.toISOString()` in the `toEqualMoment()`
+     *       custom matcher in our tests.
+     */
+    // process.env.TZ = 'Pacific/Auckland';
 };