Improve TSDoc for page object's url property. (#4297)

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();

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();
+  });
+});