[synthetics] Document the request parameter

[colleenmcginnis]

Closes #2049

Overview

Adds documentation on the new request parameter that allows users to make API requests independently of the browser interactions. For example, to get authentication credentials or tokens in service of a browser-based test.

For the reviewer

@paulb-elastic @andrewvc:

• Does it make sense to mention this initially when introducing journey?
• Does it make sense to add the examples to Working with params and secrets? From what I've read I think requesting credentials/tokens is an important use case, but I'm not sure if it makes sense to also document this functionality outside the context of params/secrets.

To do

• @colleenmcginnis @paulb-elastic @andrewvc agree on how info on the request parameter fits into the current docs
• @colleenmcginnis refine language
• @paulb-elastic @andrewvc review complete draft
• @colleenmcginnis clean up for publication
  • address feedback
  • lint content

[mergify]

This pull request does not have a backport label. Could you fix it @colleenmcginnis? 🙏
To fixup this pull request, you need to add the backport labels for the needed
branches, such as:

• backport-/d./d is the label to automatically backport to the /d./d branch. /d is the digit
  NOTE: backport-skip has been added to this pull request.

[ghost]

A documentation preview will be available soon:

• 📚 HTML diff
• 📘 Fleet and Elastic Agent Guide
• 📙 Observability Guide

[paulb-elastic]

@colleenmcginnis

Does it make sense to add the examples to Working with params and secrets?

I agree, it seems a little odd for it to go in the params and secrets section as it's out of context for the rest of that page.

I think it might be better on the write a test page. I think the reference to request you've already got there makes sense too, but maybe move the block from here to that page (maybe between add steps and setup global state)?.

[colleenmcginnis]

This is ready for review -- a few questions/comments below.

[andrewvc]

I like the new docs but found some bugs!

[paulb-elastic]

Agree that the example maybe does look a bit complex as there are other things in there about decoding that aren’t necessarily related to the request.

If the purpose of the docs is to show how a request can be made and they used in the script (irrespective of having an example in our demos are at some point), maybe a simpler example would be useful.

I’ll defer to @andrewvc’s suggestions here, but here is an example I put together for something recently (it makes a request for a quote of the day, then uses this in a Google search):

step("Google Page", async () => {
  // HTTP request for the quote
  const resp = await  request.get("http://quotes.stormconsultancy.co.uk/random.json");
  // parse the response
  quote = JSON.parse((await resp.body()).toString()).quote;
  // visit Google with the quote
  await page.goto('https://www.google.com?q=' + quote);
});

(Maybe this is too simple and not a realistic enough scenario, so feel free to use it or not)

I'll LGTM and defer to Andrew's suggestion regarding the specifics of the example.

[colleenmcginnis]

We want to mention how this is different from the other request objects that is exposed by Playwright.

@vigneshshanmugam is this what you had in mind? Are there other differences?

[vigneshshanmugam]

I was thinking something along the lines of

1. Top level request object exposed by synthetics have its own isolated cookie storage and its different from the context.request and page.request as they shares cookie storage with the corresponding BrowserContext.
2. If you want to control the creation of this request object - https://playwright.dev/docs/api/class-apirequest#api-request-new-context, you can do so by passing options via --playwright-options or synthetics.config.ts file.

[colleenmcginnis]

Thanks @vigneshshanmugam. How does this look? 0fc3fee

Here's what the whole section looks like:

[vigneshshanmugam]

Looks great, Thanks @colleenmcginnis

[vigneshshanmugam]

LGTM

I'm moving forward with other approvals -- I can make additional changes as needed in a follow-up PR.