fix(clock): amend setSystemTime docs (#32901)

Skn0tt · dgozman · web-flow · commit d3fbf1aaeb73 · 2024-10-07T12:12:12.000+02:00
As discussed yesterday over #32807. Adds some words to differentiate `setSystemTime` from `setFixedTime`. --------- Signed-off-by: Simon Knott <info@simonknott.de> Co-authored-by: Dmitry Gozman <dgozman@gmail.com>
diff --git a/docs/src/api/class-clock.md b/docs/src/api/class-clock.md
@@ -193,6 +193,8 @@ Resumes timers. Once this method is called, time resumes flowing, timers are fir
 Makes `Date.now` and `new Date()` return fixed fake time at all times,
 keeps all the timers running.
 
+Use this method for simple scenarios where you only need to test with a predefined time. For more advanced scenarios, use [`method: Clock.install`] instead. Read docs on [clock emulation](../clock.md) to learn more.
+
 **Usage**
 
 ```js
@@ -249,7 +251,7 @@ Time to be set.
 ## async method: Clock.setSystemTime
 * since: v1.45
 
-Sets current system time but does not trigger any timers.
+Sets system time, but does not trigger any timers. Use this to test how the web page reacts to a time shift, for example switching from summer to winter time, or changing time zones.
 
 **Usage**
 
diff --git a/packages/playwright-core/types/types.d.ts b/packages/playwright-core/types/types.d.ts
@@ -18544,6 +18544,10 @@ export interface Clock {
   /**
    * Makes `Date.now` and `new Date()` return fixed fake time at all times, keeps all the timers running.
    *
+   * Use this method for simple scenarios where you only need to test with a predefined time. For more advanced
+   * scenarios, use [clock.install([options])](https://playwright.dev/docs/api/class-clock#clock-install) instead. Read
+   * docs on [clock emulation](https://playwright.dev/docs/clock) to learn more.
+   *
    * **Usage**
    *
    * ```js
@@ -18557,7 +18561,8 @@ export interface Clock {
   setFixedTime(time: number|string|Date): Promise<void>;
 
   /**
-   * Sets current system time but does not trigger any timers.
+   * Sets system time, but does not trigger any timers. Use this to test how the web page reacts to a time shift, for
+   * example switching from summer to winter time, or changing time zones.
    *
    * **Usage**
    *

Original file line number	Diff line number	Diff line change
`@@ -18544,6 +18544,10 @@ export interface Clock {`
`18544`	`18544`	`/**`
`18545`	`18545`	* Makes `Date.now` and `new Date()` return fixed fake time at all times, keeps all the timers running.
`18546`	`18546`	`*`
	`18547`	`+ * Use this method for simple scenarios where you only need to test with a predefined time. For more advanced`
	`18548`	`+ * scenarios, use [clock.install([options])](https://playwright.dev/docs/api/class-clock#clock-install) instead. Read`
	`18549`	`+ * docs on [clock emulation](https://playwright.dev/docs/clock) to learn more.`
	`18550`	`+ *`
`18547`	`18551`	`* Usage`
`18548`	`18552`	`*`
`18549`	`18553`	* ```js
`@@ -18557,7 +18561,8 @@ export interface Clock {`
`18557`	`18561`	`setFixedTime(time: number\|string\|Date): Promise<void>;`
`18558`	`18562`
`18559`	`18563`	`/**`
`18560`		`- * Sets current system time but does not trigger any timers.`
	`18564`	`+ * Sets system time, but does not trigger any timers. Use this to test how the web page reacts to a time shift, for`
	`18565`	`+ * example switching from summer to winter time, or changing time zones.`
`18561`	`18566`	`*`
`18562`	`18567`	`* Usage`
`18563`	`18568`	`*`