Closes #7664: Add EngineSession.goToHistoryIndex to jump to a specific index in a sessions history.

components/browser/engine-gecko-beta/src/main/java/mozilla/components/browser/engine/gecko/GeckoEngineSession.kt

@@ -152,6 +152,13 @@ class GeckoEngineSession(
         geckoSession.goForward()
     }
 
+    /**
+     * See [EngineSession.goToHistoryIndex]
+     */
+    override fun goToHistoryIndex(index: Int) {
+        geckoSession.gotoHistoryIndex(index)
+    }
+
     /**
      * See [EngineSession.saveState]
      */

components/browser/engine-gecko-beta/src/test/java/mozilla/components/browser/engine/gecko/GeckoEngineSessionTest.kt

@@ -490,6 +490,16 @@ class GeckoEngineSessionTest {
         verify(geckoSession).goForward()
     }
 
+    @Test
+    fun goToHistoryIndex() {
+        val engineSession = GeckoEngineSession(mock(),
+            geckoSessionProvider = geckoSessionProvider)
+
+        engineSession.goToHistoryIndex(0)
+
+        verify(geckoSession).gotoHistoryIndex(0)
+    }
+
     @Test
     fun restoreState() {
         val engineSession = GeckoEngineSession(mock(),
@@ -2335,6 +2345,13 @@ class GeckoEngineSessionTest {
         fakePageLoad(false)
 
         fakePageLoad(true)
+
+        // goToHistoryIndex(index: Int)
+        engineSession.goToHistoryIndex(0)
+        verify(geckoSession).gotoHistoryIndex(0)
+        fakePageLoad(false)
+
+        fakePageLoad(true)
     }
 
     @Test

components/browser/engine-gecko-nightly/src/main/java/mozilla/components/browser/engine/gecko/GeckoEngineSession.kt

@@ -152,6 +152,13 @@ class GeckoEngineSession(
         geckoSession.goForward()
     }
 
+    /**
+     * See [EngineSession.goToHistoryIndex]
+     */
+    override fun goToHistoryIndex(index: Int) {
+        geckoSession.gotoHistoryIndex(index)
+    }
+
     /**
      * See [EngineSession.saveState]
      */

components/browser/engine-gecko-nightly/src/test/java/mozilla/components/browser/engine/gecko/GeckoEngineSessionTest.kt

@@ -490,6 +490,16 @@ class GeckoEngineSessionTest {
         verify(geckoSession).goForward()
     }
 
+    @Test
+    fun goToHistoryIndex() {
+        val engineSession = GeckoEngineSession(mock(),
+            geckoSessionProvider = geckoSessionProvider)
+
+        engineSession.goToHistoryIndex(0)
+
+        verify(geckoSession).gotoHistoryIndex(0)
+    }
+
     @Test
     fun restoreState() {
         val engineSession = GeckoEngineSession(mock(),
@@ -2335,6 +2345,13 @@ class GeckoEngineSessionTest {
         fakePageLoad(false)
 
         fakePageLoad(true)
+
+        // goToHistoryIndex(index: Int)
+        engineSession.goToHistoryIndex(0)
+        verify(geckoSession).gotoHistoryIndex(0)
+        fakePageLoad(false)
+
+        fakePageLoad(true)
     }
 
     @Test

components/browser/engine-gecko/src/main/java/mozilla/components/browser/engine/gecko/GeckoEngineSession.kt

@@ -152,6 +152,13 @@ class GeckoEngineSession(
         geckoSession.goForward()
     }
 
+    /**
+     * See [EngineSession.goToHistoryIndex]
+     */
+    override fun goToHistoryIndex(index: Int) {
+        geckoSession.gotoHistoryIndex(index)
+    }
+
     /**
      * See [EngineSession.saveState]
      */

components/browser/engine-gecko/src/test/java/mozilla/components/browser/engine/gecko/GeckoEngineSessionTest.kt

@@ -490,6 +490,16 @@ class GeckoEngineSessionTest {
         verify(geckoSession).goForward()
     }
 
+    @Test
+    fun goToHistoryIndex() {
+        val engineSession = GeckoEngineSession(mock(),
+            geckoSessionProvider = geckoSessionProvider)
+
+        engineSession.goToHistoryIndex(0)
+
+        verify(geckoSession).gotoHistoryIndex(0)
+    }
+
     @Test
     fun restoreState() {
         val engineSession = GeckoEngineSession(mock(),
@@ -2335,6 +2345,13 @@ class GeckoEngineSessionTest {
         fakePageLoad(false)
 
         fakePageLoad(true)
+
+        // goToHistoryIndex(index: Int)
+        engineSession.goToHistoryIndex(0)
+        verify(geckoSession).gotoHistoryIndex(0)
+        fakePageLoad(false)
+
+        fakePageLoad(true)
     }
 
     @Test

components/browser/engine-system/src/main/java/mozilla/components/browser/engine/system/SystemEngineSession.kt

@@ -38,7 +38,7 @@ internal val xRequestHeader = mapOf(
 /**
  * WebView-based EngineSession implementation.
  */
-@Suppress("TooManyFunctions")
+@Suppress("LargeClass", "TooManyFunctions")
 class SystemEngineSession(
     context: Context,
     private val defaultSettings: Settings? = null
@@ -125,6 +125,14 @@ class SystemEngineSession(
         webView.goForward()
     }
 
+    /**
+     * See [EngineSession.goToHistoryIndex]
+     */
+    override fun goToHistoryIndex(index: Int) {
+        val historyList = webView.copyBackForwardList()
+        webView.goBackOrForward(index - historyList.currentIndex)
+    }
+
     /**
      * See [EngineSession.saveState]
      */

components/browser/engine-system/src/test/java/mozilla/components/browser/engine/system/SystemEngineSessionTest.kt

@@ -178,6 +178,21 @@ class SystemEngineSessionTest {
         verify(webView).goForward()
     }
 
+    @Test
+    fun goToHistoryIndex() {
+        val engineSession = spy(SystemEngineSession(testContext))
+        val webView = mock<WebView>()
+
+        whenever(webView.copyBackForwardList()).thenReturn(mock())
+        engineSession.goToHistoryIndex(0)
+        verify(webView, never()).goBackOrForward(0)
+
+        engineSession.webView = webView
+
+        engineSession.goToHistoryIndex(0)
+        verify(webView).goBackOrForward(0)
+    }
+
     @Test
     fun saveState() {
         val engineSession = spy(SystemEngineSession(testContext))

components/browser/session/src/test/java/mozilla/components/browser/session/engine/EngineObserverTest.kt

@@ -54,6 +54,7 @@ class EngineObserverTest {
 
             override fun goBack() {}
             override fun goForward() {}
+            override fun goToHistoryIndex(index: Int) {}
             override fun reload() {}
             override fun stopLoading() {}
             override fun restoreState(state: EngineSessionState): Boolean { return false }
@@ -109,6 +110,7 @@ class EngineObserverTest {
 
             override fun goBack() {}
             override fun goForward() {}
+            override fun goToHistoryIndex(index: Int) {}
             override fun stopLoading() {}
             override fun reload() {}
             override fun restoreState(state: EngineSessionState): Boolean { return false }
@@ -153,6 +155,7 @@ class EngineObserverTest {
 
             override fun goBack() {}
             override fun goForward() {}
+            override fun goToHistoryIndex(index: Int) {}
             override fun stopLoading() {}
             override fun reload() {}
             override fun restoreState(state: EngineSessionState): Boolean { return false }

components/concept/engine/src/main/java/mozilla/components/concept/engine/EngineSession.kt

@@ -465,6 +465,15 @@ abstract class EngineSession(
      */
     abstract fun goForward()
 
+    /**
+     * Navigates to the specified index in the [HistoryState] of this session. The current index of
+     * this session's [HistoryState] will be updated but the items within it will be unchanged.
+     * Invalid index values are ignored.
+     *
+     * @param index the index of the session's [HistoryState] to navigate to
+     */
+    abstract fun goToHistoryIndex(index: Int)
+
     /**
      * Saves and returns the engine state. Engine implementations are not required
      * to persist the state anywhere else than in the returned map. Engines that

components/concept/engine/src/test/java/mozilla/components/concept/engine/EngineSessionTest.kt

@@ -833,6 +833,8 @@ open class DummyEngineSession : EngineSession() {
 
     override fun goForward() {}
 
+    override fun goToHistoryIndex(index: Int) {}
+
     override fun enableTrackingProtection(policy: TrackingProtectionPolicy) {}
 
     override fun disableTrackingProtection() {}

components/feature/session/src/main/java/mozilla/components/feature/session/SessionUseCases.kt

@@ -176,6 +176,26 @@ class SessionUseCases(
         }
     }
 
+    /**
+     * Use case to jump to an arbitrary history index in a session's backstack.
+     */
+    class GoToHistoryIndexUseCase internal constructor(
+        private val sessionManager: SessionManager
+    ) {
+        /**
+         * Navigates to a specific index in the [HistoryState] of the given session.
+         * Invalid index values will be ignored.
+         *
+         * @param index the index in the session's [HistoryState] to navigate to
+         * @param session the session whose [HistoryState] is being accessed
+         */
+        operator fun invoke(index: Int, session: Session? = sessionManager.selectedSession) {
+            if (session != null) {
+                sessionManager.getOrCreateEngineSession(session).goToHistoryIndex(index)
+            }
+        }
+    }
+
     class RequestDesktopSiteUseCase internal constructor(
         private val sessionManager: SessionManager
     ) {
@@ -267,6 +287,7 @@ class SessionUseCases(
     val stopLoading: StopLoadingUseCase by lazy { StopLoadingUseCase(sessionManager) }
     val goBack: GoBackUseCase by lazy { GoBackUseCase(sessionManager) }
     val goForward: GoForwardUseCase by lazy { GoForwardUseCase(sessionManager) }
+    val goToHistoryIndex: GoToHistoryIndexUseCase by lazy { GoToHistoryIndexUseCase(sessionManager) }
     val requestDesktopSite: RequestDesktopSiteUseCase by lazy { RequestDesktopSiteUseCase(sessionManager) }
     val exitFullscreen: ExitFullScreenUseCase by lazy { ExitFullScreenUseCase(sessionManager) }
     val clearData: ClearDataUseCase by lazy { ClearDataUseCase(sessionManager) }

components/feature/session/src/test/java/mozilla/components/feature/session/SessionUseCasesTest.kt

@@ -133,6 +133,25 @@ class SessionUseCasesTest {
         verify(selectedEngineSession).goForward()
     }
 
+    @Test
+    fun goToHistoryIndex() {
+        val engineSession = mock<EngineSession>()
+        val session = mock<Session>()
+
+        useCases.goToHistoryIndex(session = null, index = 0)
+        verify(engineSession, never()).goToHistoryIndex(0)
+        verify(selectedEngineSession, never()).goToHistoryIndex(0)
+
+        whenever(sessionManager.getOrCreateEngineSession(session)).thenReturn(engineSession)
+
+        useCases.goToHistoryIndex(session = session, index = 0)
+        verify(engineSession).goToHistoryIndex(0)
+
+        whenever(sessionManager.getOrCreateEngineSession(selectedSession)).thenReturn(selectedEngineSession)
+        useCases.goToHistoryIndex(index = 0)
+        verify(selectedEngineSession).goToHistoryIndex(0)
+    }
+
     @Test
     fun requestDesktopSite() {
         val engineSession = mock<EngineSession>()

docs/changelog.md

@@ -14,10 +14,14 @@ permalink: /changelog/
 
 * **feature-session**
   * Added `SessionFeature.release()`: Calling this method stops the feature from rendering sessions on the `EngineView` (until explicitly started again) and releases an already rendering session from the `EngineView`.
+  * Added `SessionUseCases.goToHistoryIndex` to allow consumers to jump to a specific index in a session's history.
 
 * **support-ktx**
   * Adds `Bundle.contentEquals` function to check if two bundles are equal.
 
+* **concept-engine**
+  * Added `EngineSession.goToHistoryIndex` to jump to a specific index in a session's history.
+  
 # 49.0.0
 
 * [Commits](https://github.com/mozilla-mobile/android-components/compare/v48.0.0...v49.0.0)