browser: implement `page.goBack()` and `page.goForward()` #5494

pkalsi97 · 2025-12-11T14:42:28Z

What?

This PR implements page.goBack() and page.goForward() to allow users to navigate through the browser's session history.

I have kept the implementation inline with Reload() and followed guidelines mentioned in the issue.

Why?

This functionality was missing and users had to rely on page.evaluate(() => window.history.back()), which is racy and unreliable for testing purposes as mentioned in the issue #5400

Example

import { browser } from 'k6/browser';
import { check } from 'k6';

export const options = {
    scenarios: {
        ui: {
            executor: 'shared-iterations',
            options: {
                browser: {
                    type: 'chromium',
                },
            },
        },
    },
};

export default async function () {
    const page = await browser.newPage();

    try {
        await page.goto('data:text/html,<h1>Page 1</h1>');
        await page.goto('data:text/html,<h1>Page 2</h1>');

        await page.goBack();
        const url1 = await page.url();
        check(url1, {
            'goBack navigated to Page 1': (u) => u.includes('Page 1') || u.includes('Page%201'),
        });

        await page.goForward();
        const url2 = await page.url();
        check(url2, {
            'goForward navigated to Page 2': (u) => u.includes('Page 2') || u.includes('Page%202'),
        });

        const nullResp = await page.goForward();
        check(nullResp, {
            'goForward at boundary returns null': (r) => r === null,
        });

    } finally {
        await page.close();
    }
}

Checklist

I have performed a self-review of my code.
I have commented on my code, particularly in hard-to-understand areas.
I have added tests for my changes.
I have run linter and tests locally (make check) and all pass.

Checklist: Documentation (only for k6 maintainers and if relevant)

Please do not merge this PR until the following items are filled out.

I have added the correct milestone and labels to the PR.
I have updated the release notes: link
I have updated or added an issue to the k6-documentation: grafana/k6-docs#NUMBER if applicable
I have updated or added an issue to the TypeScript definitions: grafana/k6-DefinitelyTyped#NUMBER if applicable

Related PR(s)/Issue(s)

Closes #5400

inancgumus

Thanks for your contribution ❤️ Please watch the test results, and see if they pass, as I ran them. I have some suggestions.

internal/js/modules/k6/browser/browser/page_mapping.go

internal/js/modules/k6/browser/common/page.go

internal/js/modules/k6/browser/common/page_options.go

internal/js/modules/k6/browser/tests/page_test.go

internal/js/modules/k6/browser/common/page.go

pkalsi97 · 2025-12-11T19:47:04Z

@inancgumus Thanks a lot for the review and feedback.

Can you add a test with a page containing iframes? I'm suspicious that returning true from here might not work as expected. Also, please add a test that goes back in a frame (if possible 🙇) 🤞

Regarding this, indeed you are right. The test are timing out. I overlooked this.
I'll take some time to investigate and resolve this.

…and update integration test

pkalsi97 · 2025-12-12T05:12:24Z

@inancgumus, I have implemented all the suggestions, thanks for pointing out a critical issue with the implementation.

Fixed the GoBack and GoForward
Removed unnecessary comments
Refactored integration test to use helper functions
Added iframe integration test for GoBack and GoForward

What ?

GoBack and GoForward methods were timing out when navigating between real HTML pages, similar was observed with iframes.

FIX

Changed the implementation to poll for URL change instead of waiting for EventFrameNavigation:

Get the target URL from the browser's navigation history (we know where we're going)
Execute NavigateToHistoryEntry()
Poll every 50ms checking if mainFrame.URL() == targetURL

Also I am not sure why 2 test were failing in ci. please guide me here.

inancgumus

Thanks for the changes @pkalsi97.

I have some suggestions, and we need to fix the git conflicts.

Don't mind those flaky tests. Your PR is fine as long as your tests pass.

internal/js/modules/k6/browser/common/page_options.go

internal/js/modules/k6/browser/tests/page_test.go

inancgumus · 2026-01-13T15:05:07Z

Hi @pkalsi97, can you fix the linter issue?

pkalsi97 · 2026-01-13T16:40:43Z

@inancgumus Done.

inancgumus

Thanks for this work, @pkalsi97 🙇 Can you merge the Page.GoBack and Page.GoForward methods into a single method called Page.GoBackForward. We'll still keep the mapping layer intact (i.e., goBack and goForward). Thanks again!

pkalsi97 · 2026-01-14T18:04:17Z

@inancgumus done, yes this completely makes sense ! thanks.

inancgumus

Nice work! 🚀

inancgumus · 2026-01-14T20:23:37Z

@pkalsi97, it would be great if you could provide updates to k6-docs and TypeScript definitions for this feature. Thanks!

pkalsi97 · 2026-01-14T20:25:41Z

@inancgumus sure. Will do by tomorrow.

ankur22

Thanks @pkalsi97 for the work on goBack and goForward! I think most of it looks good. I think I would like some clarification on a question and rethink on how we can work with lifecycle events. I took a look at Playwright's implementation and they seem to be waiting on navigation events.

ankur22 · 2026-01-15T11:48:43Z

internal/js/modules/k6/browser/common/page.go

+	// Poll for URL change, don't rely on lifecycle events since bfcache
+	// restorations don't re-fire them.


I'm not so sure about this change to working with polling.

Why can't we rely on the lifecycle event?

The WaitUntil option isn't used anywhere in the GoBackForward method.

@ankur22 Thanks for the review!

my initial implementation did use lifecycle events similar to Reload(), but test keep on timing out for real html pages and iframes, as per my knowledge EventFrameNavigation wasn't being emitted for history navigations (due to Chrome's bfcache), when we try to navigate forward or backward chrome often restore pages from memory snapshots instead or reloading them Page.frameNavigated only fires when bfcache navigation fails.

polling was used here as we know the target URL from navigation history and it updates immediately after NavigateToHistoryEntry(), making it reliable regardless of bfcache state.

Regarding WaitUntil you're right, I can remove it from the options since it's not applicable with the polling approach.

I'm fairly new to this , i'll greatly appreciate if you could fill me in on an approach that does not use polling/ any other approach that you think will be a better implementation

@pkalsi97 I'll need to take a close look at this PR and the problem you've outlined to understand why we can't work with lifecycle events and why they weren't firing -- I can see why that might be the case due to the cache. What's not clear is whether Playwright is also hitting this issue and how they have resolved it, this is important since the behaviour of k6 browser should match Playwright's if we're copying their API. I'll add my findings in this PR once I've got an answer for you.

I'll also look into it and figure it out.

Not certain if we are still waiting on this?
cc @ankur22 @inancgumus Shall we merge this as is?

mstoykov

LGTM apart from one nit and the discussion by @ankur22 on lifcycle events.

mstoykov · 2026-01-28T14:02:22Z

internal/js/modules/k6/browser/common/page.go

+	wrapTimeoutError := func(err error) error {
+		if errors.Is(err, context.DeadlineExceeded) {
+			err = &k6ext.UserFriendlyError{
+				Err:     err,
+				Timeout: opts.Timeout,
+			}
+		}
+		p.logger.Debugf("Page:GoBackForward", "timeoutCtx done: %v", err)
+		return fmt.Errorf("navigating %s to history entry %d: %w", direction, historyEntryID, err)
+	}


nit: I think this eitehr needs to be a helper function or just be inlined in the opne place it is actually used in this function

mstoykov · 2026-01-28T14:02:53Z

internal/js/modules/k6/browser/common/page.go

+	// Poll for URL change, don't rely on lifecycle events since bfcache
+	// restorations don't re-fire them.


Not certain if we are still waiting on this?
cc @ankur22 @inancgumus Shall we merge this as is?

inancgumus · 2026-01-28T15:12:02Z

@pkalsi97, we can merge this PR if you fix the conflicts (they happened in the meantime). Thank you!

codebien · 2026-01-28T15:48:32Z

@pkalsi97 @inancgumus I moved this pull request to v1.7.0 release. If in the meantime we manage to fix the conflicts then we'll move back to the upcoming v1.6.0 release.

pkalsi97 · 2026-01-28T16:35:02Z

@mstoykov Thanks for the review! @inancgumus @codebien i'll work on this shortly and try to fix it. Thanks

inancgumus · 2026-01-29T14:16:10Z

Hi @pkalsi97, since we merged the PR, can you work on the Typescript definitions and k6-docs for this feature if possible? Thank you!

pkalsi97 · 2026-01-29T14:18:07Z

@inancgumus Already implemented! Thanks

grafana/k6-docs#2166
grafana/k6-DefinitelyTyped#110

pkalsi97 requested a review from a team as a code owner December 11, 2025 14:42

pkalsi97 requested review from inancgumus and mstoykov and removed request for a team December 11, 2025 14:42

inancgumus reviewed Dec 11, 2025

View reviewed changes

pkalsi97 temporarily deployed to azure-trusted-signing December 11, 2025 18:43 — with GitHub Actions Inactive

pkalsi97 temporarily deployed to azure-trusted-signing December 11, 2025 18:46 — with GitHub Actions Inactive

pkalsi97 added 3 commits December 12, 2025 09:06

browser: implement page.goBack() and page.goForward()

6aae38c

refactor tracing tests to use page.goBack()

a4c1e29

implement feedback, resolve GoBack/GoForward timeout with real pages …

a2bc909

…and update integration test

pkalsi97 force-pushed the feat/5400 branch from 4094412 to a2bc909 Compare December 12, 2025 05:02

pkalsi97 requested a review from inancgumus December 12, 2025 05:12

pkalsi97 temporarily deployed to azure-trusted-signing December 12, 2025 08:15 — with GitHub Actions Inactive

pkalsi97 temporarily deployed to azure-trusted-signing December 12, 2025 08:17 — with GitHub Actions Inactive

inancgumus reviewed Dec 12, 2025

View reviewed changes

internal/js/modules/k6/browser/common/page_options.go Outdated Show resolved Hide resolved

internal/js/modules/k6/browser/common/page_options.go Outdated Show resolved Hide resolved

internal/js/modules/k6/browser/tests/page_test.go Outdated Show resolved Hide resolved

pkalsi97 added 2 commits December 12, 2025 22:58

implement feedback, refactor options parsing and add test helpers

55ba0be

Merge branch 'master' into feat/5400

6f39d7c

pkalsi97 requested a review from inancgumus December 12, 2025 17:46

pkalsi97 temporarily deployed to azure-trusted-signing January 6, 2026 11:18 — with GitHub Actions Inactive

pkalsi97 temporarily deployed to azure-trusted-signing January 6, 2026 11:20 — with GitHub Actions Inactive

inancgumus added this to the v1.6.0 milestone Jan 6, 2026

pkalsi97 added 2 commits January 13, 2026 21:56

Merge branch 'master' into feat/5400

1b20fb0

chore: fix linting error in browser tests

3e457b7

pkalsi97 temporarily deployed to azure-trusted-signing January 13, 2026 21:48 — with GitHub Actions Inactive

pkalsi97 temporarily deployed to azure-trusted-signing January 13, 2026 21:50 — with GitHub Actions Inactive

inancgumus reviewed Jan 14, 2026

View reviewed changes

browser: refactor GoBack/GoForward into unified GoBackForward method

444abb6

pkalsi97 requested a review from inancgumus January 14, 2026 18:04

Merge branch 'master' into feat/5400

3c9b001

inancgumus requested a review from ankur22 January 14, 2026 20:16

pkalsi97 temporarily deployed to azure-trusted-signing January 14, 2026 20:22 — with GitHub Actions Inactive

inancgumus approved these changes Jan 14, 2026

View reviewed changes

pkalsi97 temporarily deployed to azure-trusted-signing January 14, 2026 20:24 — with GitHub Actions Inactive

This was referenced Jan 15, 2026

Add documentation for page.goBack() and page.goForward() grafana/k6-docs#2166

Merged

add TypeScript definitions for page.goBack() and page.goForward() grafana/k6-DefinitelyTyped#110

Merged

ankur22 reviewed Jan 15, 2026

View reviewed changes

pkalsi97 requested a review from ankur22 January 18, 2026 07:02

inancgumus added the blocked issue's resolution is blocked label Jan 28, 2026

mstoykov approved these changes Jan 28, 2026

View reviewed changes

codebien modified the milestones: v1.6.0, v1.7.0 Jan 28, 2026

Merge branch 'master' into feat/5400

53c85af

pkalsi97 temporarily deployed to azure-trusted-signing January 28, 2026 17:26 — with GitHub Actions Inactive

pkalsi97 temporarily deployed to azure-trusted-signing January 28, 2026 17:28 — with GitHub Actions Inactive

AgnesToulet merged commit 2fec46b into grafana:master Jan 29, 2026
49 checks passed

AgnesToulet modified the milestones: v1.7.0, v1.6.0 Jan 29, 2026

inancgumus removed the blocked issue's resolution is blocked label Jan 29, 2026

		// Poll for URL change, don't rely on lifecycle events since bfcache
		// restorations don't re-fire them.

browser: implement page.goBack() and page.goForward() #5494

browser: implement page.goBack() and page.goForward() #5494

Conversation

pkalsi97 commented Dec 11, 2025

What?

Why?

Example

Checklist

Checklist: Documentation (only for k6 maintainers and if relevant)

Related PR(s)/Issue(s)

Uh oh!

inancgumus left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

pkalsi97 commented Dec 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

pkalsi97 commented Dec 12, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What ?

FIX

Uh oh!

inancgumus left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

inancgumus commented Jan 13, 2026

Uh oh!

pkalsi97 commented Jan 13, 2026

Uh oh!

inancgumus left a comment

Choose a reason for hiding this comment

Uh oh!

pkalsi97 commented Jan 14, 2026

Uh oh!

inancgumus left a comment

Choose a reason for hiding this comment

Uh oh!

inancgumus commented Jan 14, 2026

Uh oh!

pkalsi97 commented Jan 14, 2026

Uh oh!

ankur22 left a comment

Choose a reason for hiding this comment

Uh oh!

ankur22 Jan 15, 2026

Choose a reason for hiding this comment

Uh oh!

pkalsi97 Jan 16, 2026

Choose a reason for hiding this comment

Uh oh!

ankur22 Jan 19, 2026

Choose a reason for hiding this comment

Uh oh!

pkalsi97 Jan 19, 2026

Choose a reason for hiding this comment

Uh oh!

mstoykov Jan 28, 2026

Choose a reason for hiding this comment

Uh oh!

mstoykov left a comment

Choose a reason for hiding this comment

Uh oh!

mstoykov Jan 28, 2026

Choose a reason for hiding this comment

Uh oh!

mstoykov Jan 28, 2026

Choose a reason for hiding this comment

browser: implement `page.goBack()` and `page.goForward()` #5494

browser: implement `page.goBack()` and `page.goForward()` #5494

pkalsi97 commented Dec 11, 2025 •

edited

Loading

pkalsi97 commented Dec 12, 2025 •

edited

Loading

pkalsi97 commented Jan 28, 2026 •

edited

Loading