Browser: add route.fulfill #4961

AgnesToulet · 2025-07-22T13:22:06Z

What?

This PR adds the route.fulfill function. Used in page.route, it allows to fulfill a request with a given response.

Why?

This helps with Playwright compatibility and allow to mock requests while testing.

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)

Part of #4502

Known limitation

As you can see in the test script below, if you want to fulfill a request to an external website you need to handle CORS yourself. Playwright had the same issue described here with multiple proposed solution. They fixed it by adding CORS for external request if no overrides are provided: see this function. I tried to do the same but struggled with the request origin not being set on our side. I don't think it's blocking this PR though but I'd like to know your thoughts about this issue, if we should try to follow Playwright or choose another option (document it or allow it if an option is set).

Test script

To test the full workflow, I'm using the following k6 script. It's not part of the PR because it depends on a change on quickpizza: grafana/quickpizza#225 but you can play with it if you run QuickPizza locally.

import { check, sleep } from "k6";
import { browser } from "k6/browser";

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

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

	await page.route(
		"https://jsonplaceholder.typicode.com/todos/1",
		function (route) {
			console.log("Intercepting request to external API");
			route.fulfill({
				status: 200,
				body: JSON.stringify({
					id: 1,
					title: "Test Todo",
					completed: false,
				}),
				contentType: "application/json",
				headers: {
					"Access-Control-Allow-Origin": "*",
					"Access-Control-Allow-Credentials": "true",
				},
			});
		}
	);

	await page.goto("http://localhost:3333/browser.php");

	await page.getByRole("button", { name: "external data" }).click();

	sleep(1);

	const checkData = await page.locator("#external-data-display").innerText();
	check(page, {
		externalData: checkData === "External data: Test Todo",
	});

	sleep(3);

	await page.close();
}

inancgumus

Good work, despite it being your first PRs 🙇. I've posted some suggestions. We should also fix the linter errors.

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

inancgumus · 2025-07-22T21:48:18Z

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

@@ -0,0 +1,73 @@
+package common


I'm not sure about this refactoring. I'd keep all HTTP-related code in http.go as before, as I don't mind about the file line length. No strong opinion, though.

I'll revert this change! Now that I think again about this, I think it makes sense to keep it in http.go. And if the file size becomes an issue, it would probably make more sense to split it into three to have response.go, request.go and route.go. Reverted in 2e31eae

❤️ In that case, I'd suggest http_response.go, http_request.go, etc.

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

oleiade

Great job @AgnesToulet 👏🏻 Nothing stood out to me, besides what @inancgumus mentioned, so I'll wait on his further review comments to 👍🏻

ankur22

Nice! Looks good. Just a couple of things to consider first before we can merge this in.

ankur22 · 2025-07-25T12:45:37Z

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

-	route.Continue()
+
+	if err := route.Continue(); err != nil {
+		m.logger.Warnf("FrameManager:requestStarted",


Should this also be an error log, like it is in onRequestPaused?

I believe the other one better be a warning to reduce log clutter.

I think this one is important because if it fails, it means than the request is stalling and navigation will probably never ends. But at the same time, there is no user option here so I don't know what the user can do about this error (same for the other one in onRequestPaused, pretty important but not much users can do about it).

Updated in 55db130 for consistency. I have no strong opinion on the log level but I think it should not happen often and is important enough to be an error.

I'm okay with using the "error" level for logging. However, if this routing issue is caused by a non-mainframe navigation, such as a CSS route, it could lead to an increase in log entries. This was a significant problem in the past, as we were logging numerous errors that were not related to the success or failure of test runs.

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

The base branch was changed.

AgnesToulet · 2025-07-29T13:47:11Z

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

+
+	action := fetch.FulfillRequest(request.interceptionID, responseCode)
+
+	if opts.ContentType != "" {


I'm wondering here... Is it better to keep it like this or actually remove this field from the FulfillOptions struct and directly add it to the Headers option field in parseFulfillOptions method, WDYT?

I believe it's better to be as close to Playwright as possible in UX terms.

Yes I agree, this would only be "under the hood". The API spec would stay the same but we wouldn't bother with this field in the other layers of the codebase.

mstoykov · 2025-07-31T12:24:46Z

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

+		case "body":
+			fopts.Body = obj.Get(k).String()


Same comment as I gave in the continue PR - this should use common.ToBytes and handle this as binary data by the most part.

Updated in adc5394

mstoykov · 2025-07-31T12:27:25Z

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

+			}
+		case "status":
+			fopts.Status = obj.Get(k).ToInteger()
+		}


Looking at https://playwright.dev/docs/api/class-route#route-fulfill - you are not handling path, json and response . Can we have a comment here. Also I feel like handling all but response is likely fairly quick 🤔 .

But if not maybe lets throw an exception instead of silently doing the wrong thing

I think we should be ok to wait for feedback for response and json.

Instead of working with path we should probably encourage users to work with the current idiomatic k6 way of reading a file and then passing it the bytes to body.

So, yeah, happy with throwing an error if a user tries to work with those fields that aren't implemented.

Updated in 67f24be

I agree that json should be quick to implement and used by a lot of users but wanted to keep the scope of the PR as small as possible. We can definitely iterate on it in future releases.

* Refactor: move route types and function to its own file * Refactor: add route mapping and return errors * Add fulfill function * Add fulfill test * add comments * move back route struct to http.go * add request mapping * remove forgotten log * fix linter issues * rename var * remove pointer to fulfilloptions * remove extra return * update log level to keep it consistent * support buffer in body input * return error for unsupported options

AgnesToulet requested a review from a team as a code owner July 22, 2025 13:22

AgnesToulet requested review from inancgumus and oleiade and removed request for a team July 22, 2025 13:22

AgnesToulet added enhancement area: browser browser: playwright related to Playwright compatibility labels Jul 22, 2025

AgnesToulet added this to the v1.2.0 milestone Jul 22, 2025

AgnesToulet mentioned this pull request Jul 22, 2025

Browser: add page.route #4953

Merged

8 tasks

inancgumus reviewed Jul 22, 2025

View reviewed changes

oleiade reviewed Jul 23, 2025

View reviewed changes

inancgumus previously approved these changes Jul 24, 2025

View reviewed changes

oleiade previously approved these changes Jul 25, 2025

View reviewed changes

ankur22 reviewed Jul 25, 2025

View reviewed changes

Base automatically changed from agnestoulet/poc-page-route to master July 29, 2025 11:33

AgnesToulet added 10 commits July 29, 2025 15:19

Refactor: move route types and function to its own file

d48013d

Refactor: add route mapping and return errors

f033f0e

Add fulfill function

49e4e61

Add fulfill test

fabd831

add comments

3f5b581

move back route struct to http.go

1926565

add request mapping

9d91850

remove forgotten log

50596d6

fix linter issues

9955970

rename var

4a66aa0

AgnesToulet force-pushed the browser/add-route-fulfill branch from c2e8aaf to 4a66aa0 Compare July 29, 2025 13:24

AgnesToulet added 2 commits July 29, 2025 15:40

remove pointer to fulfilloptions

4452b9e

remove extra return

0ed7528

AgnesToulet commented Jul 29, 2025

View reviewed changes

AgnesToulet force-pushed the browser/add-route-fulfill branch from eb86c95 to 0ed7528 Compare July 29, 2025 14:19

update log level to keep it consistent

55db130

AgnesToulet requested review from ankur22, inancgumus and oleiade July 29, 2025 14:23

mstoykov reviewed Jul 31, 2025

View reviewed changes

ankur22 previously approved these changes Jul 31, 2025

View reviewed changes

oleiade previously approved these changes Jul 31, 2025

View reviewed changes

support buffer in body input

adc5394

AgnesToulet dismissed stale reviews from oleiade and ankur22 via adc5394 August 1, 2025 07:33

return error for unsupported options

67f24be

mstoykov approved these changes Aug 1, 2025

View reviewed changes

ankur22 approved these changes Aug 1, 2025

View reviewed changes

AgnesToulet merged commit 4e5fec9 into master Aug 1, 2025
47 of 48 checks passed

AgnesToulet deleted the browser/add-route-fulfill branch August 1, 2025 08:47

This was referenced Aug 1, 2025

Browser: add route-related doc grafana/k6-docs#2018

Merged

Browser: add route-related functions grafana/k6-DefinitelyTyped#88

Merged

BrewTestBot mentioned this pull request Aug 13, 2025

k6 1.2.1 Homebrew/homebrew-core#233339

Merged


		action := fetch.FulfillRequest(request.interceptionID, responseCode)

		if opts.ContentType != "" {

Browser: add route.fulfill #4961

Browser: add route.fulfill #4961

Conversation

AgnesToulet commented Jul 22, 2025 • edited by ankur22 Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What?

Why?

Checklist

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

Related PR(s)/Issue(s)

Known limitation

Test script

Uh oh!

inancgumus left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

AgnesToulet Jul 24, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

oleiade left a comment

Choose a reason for hiding this comment

Uh oh!

ankur22 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

inancgumus Jul 25, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

AgnesToulet Aug 1, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

AgnesToulet commented Jul 22, 2025 •

edited by ankur22

Loading

inancgumus left a comment •

edited

Loading

AgnesToulet Jul 24, 2025 •

edited

Loading

inancgumus Jul 25, 2025 •

edited

Loading

AgnesToulet Aug 1, 2025 •

edited

Loading