refactor: move navigation related api to navigationHistory

electron · VerteDinde · Jun 5, 2024 · Mar 31, 2024 · May 3, 2024 · May 28, 2024
commit 9dbdda1c5eee30b635b53d57bf06fb2bdd5f1349
diff --git a/docs/api/navigation-history.md b/docs/api/navigation-history.md
@@ -9,6 +9,24 @@ Each navigation entry corresponds to a specific page. The indexing system follow
 
 ### Instance Methods
 
+#### `navigationHistory.canGoBack()`
+
+Returns `boolean` - Whether the browser can go back to previous web page.
+
+#### `navigationHistory.canGoForward()`
+
+Returns `boolean` - Whether the browser can go forward to next web page.
+
+#### `navigationHistory.canGoToOffset(offset)`
+
+* `offset` Integer
+
+Returns `boolean` - Whether the web page can go to `offset`.
+
+#### `navigationHistory.clear()`
+
+Clears the navigation history.
+
 #### `navigationHistory.getActiveIndex()`
 
 Returns `Integer` - The index of the current page, from which we would go back/forward or reload.
@@ -24,6 +42,26 @@ Returns `Object`:
 
 If index is out of bounds (greater than history length or less than 0), null will be returned.
 
+#### `navigationHistory.goBack()`
+
+Makes the browser go back a web page.
+
+#### `navigationHistory.goForward()`
+
+Makes the browser go forward a web page.
+
+#### `navigationHistory.goToIndex(index)`
+
+* `index` Integer
+
+Navigates browser to the specified absolute web page index.
+
+#### `navigationHistory.goToOffset(offset)`
+
+* `offset` Integer
+
+Navigates to the specified offset from the "current entry".
+
 #### `navigationHistory.length()`
 
 Returns `Integer` - History length.
diff --git a/lib/browser/api/web-contents.ts b/lib/browser/api/web-contents.ts
@@ -537,6 +537,14 @@ WebContents.prototype._init = function () {
   // maintaining a list of navigation entries for backward and forward navigation.
   Object.defineProperty(this, 'navigationHistory', {
     value: {
+      canGoBack: this.canGoBack.bind(this),
+      canGoForward: this.canGoForward.bind(this),
+      canGoToOffset: this.canGoToOffset.bind(this),
+      clear: this.clearHistory.bind(this),
+      goBack: this.goBack.bind(this),
+      goForward: this.goForward.bind(this),
+      goToIndex: this.goToIndex.bind(this),
+      goToOffset: this.goToOffset.bind(this),
       getActiveIndex: this._getActiveIndex.bind(this),
       length: this._historyLength.bind(this),
       getEntryAtIndex: this._getNavigationEntryAtIndex.bind(this)

diff --git a/spec/api-web-contents-spec.ts b/spec/api-web-contents-spec.ts
@@ -567,6 +567,84 @@ describe('webContents module', () => {
       w = new BrowserWindow({ show: false });
     });
     afterEach(closeAllWindows);
+    describe('navigationHistory.canGoBack and navigationHistory.goBack API', () => {
+      it('should not be able to go back if history is empty', async () => {
+        expect(w.webContents.navigationHistory.canGoBack()).to.be.false();
+      });
+
+      it('should be able to go back if history is not empty', async () => {
+        await w.loadURL(urlPage1);
+        await w.loadURL(urlPage2);
+        expect(w.webContents.navigationHistory.getActiveIndex()).to.equal(1);
+        expect(w.webContents.navigationHistory.canGoBack()).to.be.true();
+        w.webContents.navigationHistory.goBack();
+        expect(w.webContents.navigationHistory.getActiveIndex()).to.equal(0);
+      });
+    });
+
+    describe('navigationHistory.canGoForward and navigationHistory.goForward API', () => {
+      it('should not be able to go forward if history is empty', async () => {
+        expect(w.webContents.navigationHistory.canGoForward()).to.be.false();
+      });
+
+      it('should not be able to go forward if current index is same as history length', async () => {
+        await w.loadURL(urlPage1);
+        await w.loadURL(urlPage2);
+        expect(w.webContents.navigationHistory.canGoForward()).to.be.false();
+      });
+
+      it('should be able to go forward if history is not empty and active index is less than history length', async () => {
+        await w.loadURL(urlPage1);
+        await w.loadURL(urlPage2);
+        w.webContents.navigationHistory.goBack();
+        expect(w.webContents.navigationHistory.getActiveIndex()).to.equal(0);
+        expect(w.webContents.navigationHistory.canGoForward()).to.be.true();
+        w.webContents.navigationHistory.goForward();
+        expect(w.webContents.navigationHistory.getActiveIndex()).to.equal(1);
+      });
+    });
+
+    describe('navigationHistory.canGoToOffset(index) and navigationHistory.goToOffset(index) API', () => {
+      it('should not be able to go to invalid offset', async () => {
+        expect(w.webContents.navigationHistory.canGoToOffset(-1)).to.be.false();
+        expect(w.webContents.navigationHistory.canGoToOffset(10)).to.be.false();
+      });
+
+      it('should be able to go to valid negative offset', async () => {
+        await w.loadURL(urlPage1);
+        await w.loadURL(urlPage2);
+        await w.loadURL(urlPage3);
+        expect(w.webContents.navigationHistory.canGoToOffset(-2)).to.be.true();
+        expect(w.webContents.navigationHistory.getActiveIndex()).to.equal(2);
+        w.webContents.navigationHistory.goToOffset(-2);
+        expect(w.webContents.navigationHistory.getActiveIndex()).to.equal(0);
+      });
+
+      it('should be able to go to valid positive offset', async () => {
+        await w.loadURL(urlPage1);
+        await w.loadURL(urlPage2);
+        await w.loadURL(urlPage3);
+
+        w.webContents.navigationHistory.goBack();
+        expect(w.webContents.navigationHistory.canGoToOffset(1)).to.be.true();
+        expect(w.webContents.navigationHistory.getActiveIndex()).to.equal(1);
+        w.webContents.navigationHistory.goToOffset(1);
+        expect(w.webContents.navigationHistory.getActiveIndex()).to.equal(2);
+      });
+    });
+
+    describe('navigationHistory.clear API', () => {
+      it('should be able clear history', async () => {
+        await w.loadURL(urlPage1);
+        await w.loadURL(urlPage2);
+        await w.loadURL(urlPage3);
+
+        expect(w.webContents.navigationHistory.length()).to.equal(3);
+        w.webContents.navigationHistory.clear();
+        expect(w.webContents.navigationHistory.length()).to.equal(1);
+      });
+    });
+
     describe('navigationHistory.getEntryAtIndex(index) API ', () => {
       it('should fetch default navigation entry when no urls are loaded', async () => {
         const result = w.webContents.navigationHistory.getEntryAtIndex(0);