From 3b4a800d198757962d58ad218daeb3be36be96b4 Mon Sep 17 00:00:00 2001
From: Priyansh Garg <priyanshgarg30@gmail.com>
Date: Mon, 11 Nov 2024 03:37:02 +0530
Subject: [PATCH] Improve TSDoc for page object's url property. (#4297)

---
 types/page-object.d.ts            | 14 ++++++++-
 types/tests/page-object.test-d.ts | 47 +++++++++++++++++++++++++++++++
 2 files changed, 60 insertions(+), 1 deletion(-)
 create mode 100644 types/tests/page-object.test-d.ts

diff --git a/types/page-object.d.ts b/types/page-object.d.ts
index 1e663c135d..b6420a53e7 100644
--- a/types/page-object.d.ts
+++ b/types/page-object.d.ts
@@ -507,7 +507,19 @@ export type EnhancedPageObject<
   > &
   Required<MergeObjectsArray<Commands>> & {
     /**
-     * A url or function returning a url to be used in a url() command when the page's navigate() method is called.
+     * A url or a function returning a url. This is also used internally when the page's navigate() method is called.
+     *
+     * By default, the url property is set to a string type. To set it to a function type instead, the fifth type parameter
+     * of the `EnhancedPageObject` interface can be used:
+     *
+     * ```
+     * export interface MyPage extends
+     *   EnhancedPageObject<{}, typeof elements, {}, {}, () => string> {}
+     * ```
+     *
+     * See the usage of the `EnhancedPageObject` interface
+     * [here](https://github.com/nightwatchjs-community/nightwatch-typescript-boilerplate/blob/0bf15a6e8735b576b82bce9a7bb5c6beddb14de4/nightwatch/pages/FileUpload.ts#L17)
+     * for reference.
      *
      * @example
      * const homePageObject = browser.page.homePage();
diff --git a/types/tests/page-object.test-d.ts b/types/tests/page-object.test-d.ts
new file mode 100644
index 0000000000..35becd3085
--- /dev/null
+++ b/types/tests/page-object.test-d.ts
@@ -0,0 +1,47 @@
+// Page object file
+import {EnhancedPageObject, PageObjectModel} from '..';
+
+const fileUploadPageElements = {
+  fileUploadInput: 'input#file-upload',
+  submitButton: 'input#file-submit',
+  uploadFiles: '#uploaded-files'
+};
+
+const fileUploadPage = {
+  url(this: EnhancedPageObject) {
+    return `${this.api.launch_url}/upload`;
+  },
+  elements: fileUploadPageElements
+} satisfies PageObjectModel;
+
+export interface FileUploadPage extends
+  EnhancedPageObject<{}, typeof fileUploadPageElements, {}, {}, () => string> {} // eslint-disable-line @typescript-eslint/ban-types
+
+export default fileUploadPage;
+
+
+// Declare the newly created page object in the NightwatchCustomPageObjects interface.
+// This will allow you to access the page object type in your test files.
+declare module '..' {
+  interface NightwatchCustomPageObjects {
+    FileUpload(): FileUploadPage;
+  }
+}
+
+
+// test file
+describe('File Upload', function() {
+  it('File Upload test', function() {
+    const fileUploadPage = browser.page.FileUpload();
+    const url = fileUploadPage.url();
+
+    fileUploadPage
+      .navigate(url)
+      .uploadFile('@fileUploadInput', 'test.txt')
+      // alternate way of passing an element instead of '@submitButton'
+      .click(fileUploadPage.elements.submitButton)
+      .expect.element('@uploadFiles').text.to.equal('test.txt');
+
+    browser.end();
+  });
+});