From b926446a5c327feeac639a3067450f4877a9fadc Mon Sep 17 00:00:00 2001
From: bitloi <89318445+bitloi@users.noreply.github.com>
Date: Sat, 17 Jan 2026 09:05:58 -0500
Subject: [PATCH] feat: add screenshot delay option for Browser Engine monitor
 (#6753)

Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com>
Co-authored-by: Frank Elsinga <frank@elsinga.de>
---
 .../2026-01-16-0000-add-screenshot-delay.js   | 11 +++++++
 server/model/monitor.js                       | 22 +++++++++++++
 .../real-browser-monitor-type.js              |  5 +++
 src/lang/en.json                              |  4 +++
 src/pages/EditMonitor.vue                     | 31 +++++++++++++++++++
 5 files changed, 73 insertions(+)
 create mode 100644 db/knex_migrations/2026-01-16-0000-add-screenshot-delay.js

diff --git a/db/knex_migrations/2026-01-16-0000-add-screenshot-delay.js b/db/knex_migrations/2026-01-16-0000-add-screenshot-delay.js
new file mode 100644
index 000000000..fa0829bdf
--- /dev/null
+++ b/db/knex_migrations/2026-01-16-0000-add-screenshot-delay.js
@@ -0,0 +1,11 @@
+exports.up = function (knex) {
+    return knex.schema.alterTable("monitor", function (table) {
+        table.integer("screenshot_delay").notNullable().unsigned().defaultTo(0);
+    });
+};
+
+exports.down = function (knex) {
+    return knex.schema.alterTable("monitor", function (table) {
+        table.dropColumn("screenshot_delay");
+    });
+};
diff --git a/server/model/monitor.js b/server/model/monitor.js
index e01977133..2a23abd2f 100644
--- a/server/model/monitor.js
+++ b/server/model/monitor.js
@@ -1764,6 +1764,28 @@ class Monitor extends BeanModel {
                 this.timeout = pingGlobalTimeout;
             }
         }
+
+        if (this.type === "real-browser") {
+            // screenshot_delay validation
+            if (this.screenshot_delay !== undefined && this.screenshot_delay !== null) {
+                const delay = Number(this.screenshot_delay);
+                if (isNaN(delay) || delay < 0) {
+                    throw new Error("Screenshot delay must be a non-negative number");
+                }
+
+                // Must not exceed 0.8 * timeout (page.goto timeout is interval * 1000 * 0.8)
+                const maxDelayFromTimeout = this.interval * 1000 * 0.8;
+                if (delay >= maxDelayFromTimeout) {
+                    throw new Error(`Screenshot delay must be less than ${maxDelayFromTimeout}ms (0.8 × interval)`);
+                }
+
+                // Must not exceed 0.5 * interval to prevent blocking next check
+                const maxDelayFromInterval = this.interval * 1000 * 0.5;
+                if (delay >= maxDelayFromInterval) {
+                    throw new Error(`Screenshot delay must be less than ${maxDelayFromInterval}ms (0.5 × interval)`);
+                }
+            }
+        }
     }
 
     /**
diff --git a/server/monitor-types/real-browser-monitor-type.js b/server/monitor-types/real-browser-monitor-type.js
index 2b62a10a3..32fa36f1a 100644
--- a/server/monitor-types/real-browser-monitor-type.js
+++ b/server/monitor-types/real-browser-monitor-type.js
@@ -269,6 +269,11 @@ class RealBrowserMonitorType extends MonitorType {
             timeout: monitor.interval * 1000 * 0.8,
         });
 
+        // Wait for additional time before taking screenshot if configured
+        if (monitor.screenshot_delay > 0) {
+            await page.waitForTimeout(monitor.screenshot_delay);
+        }
+
         let filename = jwt.sign(monitor.id, server.jwtSecret) + ".png";
 
         await page.screenshot({
diff --git a/src/lang/en.json b/src/lang/en.json
index 4c8ebffa8..72e8beaa6 100644
--- a/src/lang/en.json
+++ b/src/lang/en.json
@@ -1055,6 +1055,10 @@
     "remoteBrowserToggle": "By default Chromium runs inside the Uptime Kuma container. You can use a remote browser by toggling this switch.",
     "useRemoteBrowser": "Use a Remote Browser",
     "deleteRemoteBrowserMessage": "Are you sure want to delete this Remote Browser for all monitors?",
+    "Screenshot Delay": "Screenshot Delay (waits {milliseconds})",
+    "milliseconds": "{n} millisecond | {n} milliseconds",
+    "screenshotDelayDescription": "Optionally wait this many milliseconds before taking the screenshot. Maximum: {maxValueMs}ms (0.5 × interval).",
+    "screenshotDelayWarning": "Higher values keep the browser open longer, which may increase memory usage with many concurrent monitors.",
     "GrafanaOncallUrl": "Grafana Oncall URL",
     "systemService": "System Service",
     "systemServiceName": "Service Name",
diff --git a/src/pages/EditMonitor.vue b/src/pages/EditMonitor.vue
index 9531210d1..6cb93c19e 100644
--- a/src/pages/EditMonitor.vue
+++ b/src/pages/EditMonitor.vue
@@ -1263,6 +1263,36 @@
                                 <div class="form-text"></div>
                             </div>
 
+                            <!-- Screenshot Delay - Real Browser only -->
+                            <div v-if="monitor.type === 'real-browser'" class="my-3">
+                                <label for="screenshot-delay" class="form-label">
+                                    {{
+                                        $t("Screenshot Delay", {
+                                            milliseconds: $t("milliseconds", monitor.screenshot_delay),
+                                        })
+                                    }}
+                                </label>
+                                <input
+                                    id="screenshot-delay"
+                                    v-model="monitor.screenshot_delay"
+                                    type="number"
+                                    class="form-control"
+                                    min="0"
+                                    :max="Math.floor(monitor.interval * 1000 * 0.5)"
+                                    step="100"
+                                />
+                                <div class="form-text">
+                                    {{
+                                        $t("screenshotDelayDescription", {
+                                            maxValueMs: Math.floor(monitor.interval * 1000 * 0.5),
+                                        })
+                                    }}
+                                </div>
+                                <div v-if="monitor.screenshot_delay" class="form-text text-warning">
+                                    {{ $t("screenshotDelayWarning") }}
+                                </div>
+                            </div>
+
                             <div v-if="showDomainExpiryNotification" class="my-3 form-check">
                                 <input
                                     id="domain-expiry-notification"
@@ -2293,6 +2323,7 @@ const monitorDefaults = {
     kafkaProducerAllowAutoTopicCreation: false,
     gamedigGivenPortOnly: true,
     remote_browser: null,
+    screenshot_delay: 0,
     rabbitmqNodes: [],
     rabbitmqUsername: "",
     rabbitmqPassword: "",