Improving and padding the workshop content in readiness for backup selector paths

content/en/ninja-workshops/4-synthetics-scripting/1-real-browser-test/1-recording-a-test.md

@@ -3,6 +3,8 @@ title: 1.1 Recording a test
 weight: 1
 ---
 
+In this step you'll capture a complete user journey through the demo Online Boutique storefront using the Chrome DevTools Recorder. The recorder watches your interactions and records each click, keystroke, and navigation as a structured step. For every element you interact with it captures **multiple selector strategies** (CSS, XPath, etc.), so the resulting test is robust against most front-end changes — if one selector breaks the next is tried in turn. You'll save the recording to a JSON file that you'll import into Splunk Synthetic Monitoring in the next step.
+
 ## Open the starting URL
 
 Open the starting URL for the workshop in Chrome. Click on the appropriate link below to open the site in a new tab.
@@ -31,7 +33,7 @@ Next, open the Developer Tools (in the new tab that was opened above) by pressin
 ![Open Recorder](../../img/open-recorder.png)
 
 {{% notice title="Note" style="info" %}}
-Site elements might change depending on viewport width. Before recording, set your browser window to the correct width for the test you want to create (Desktop, Tablet, or Mobile). Change the DevTools "dock side" to pop out as a separate window if it helps.
+Site elements might change depending on viewport width. Before recording, set your browser window to the correct width for the test you want to create (Desktop, Tablet, or Mobile). Responsive sites often hide menu items behind a hamburger icon below a breakpoint — recording a "click the cart link" on a wide window won't replay correctly if the test runs at a mobile viewport. Change the DevTools "dock side" to pop out as a separate window if it helps.
 {{% /notice %}}
 
 ## Create a new recording
@@ -67,6 +69,14 @@ Select **JSON** as the format, then click on **Save**
 
 **Congratulations!** You have successfully created a recording using the Chrome DevTools Recorder. Next, we will use this recording to create a Real Browser Test in Splunk Synthetic Monitoring.
 
+### What's actually in the JSON?
+
+Open the expandable below if you'd like to inspect the recording. A few things worth noticing:
+
+- Each interaction is an object with a `type` (`navigate`, `click`, etc.) and a list of `selectors` — that's the multi-strategy fallback we mentioned at the start. The recorder lists them in priority order; the test runner tries each until one matches.
+- The first step is a `setViewport`, which pins the window dimensions so the test always replays at the same size regardless of which location it runs from.
+- Most click steps include `assertedEvents` with a `navigation` URL and page `title`. These are the recorder's way of locking in expected outcomes — if a click *should* result in a navigation to `/cart` and it doesn't, the step fails. You'll see this surface in run results as a clear assertion failure rather than a vague timeout.
+
 ---
 
 {{% expand "Click here to view the JSON file" %}}

content/en/ninja-workshops/4-synthetics-scripting/1-real-browser-test/2-create-real-browser-test.md

@@ -3,12 +3,18 @@ title: 1.2 Create Real Browser Test
 weight: 2
 ---
 
-In Splunk Observability Cloud, navigate to **Synthetics** and click on {{% button style="blue" %}}Add new test{{% /button %}}.
+The recording you just saved is a local file — it can't fail an alert, can't run from London at 3am, and can't tell you whether checkout was slow yesterday. Moving from a recording to a Splunk Synthetic Monitoring test is what unlocks all of that: the same user journey, now executed continuously from cloud locations you choose, with results that flow into the same Observability Cloud organisation as your metrics, logs, and traces.
 
-From the dropdown select **Browser test**.
+In Splunk Observability Cloud, navigate to **Synthetics**. The landing page surfaces the three Synthetic Monitoring check types:
+
+- **Browser tests** — the full-Chromium real-user-journey checks we're building today.
+- **Uptime tests** — lightweight port and HTTP availability checks.
+- **API tests** — multi-step HTTP transaction checks (we'll build one in Part 2).
+
+Click on {{% button style="blue" %}}Add new test{{% /button %}} and select **Browser test** from the dropdown.
 
 ![Add new test](../../img/add-new-test.png)
 
-You will then be presented with the **Browser test content** configuration page.
+You will then be presented with the **Browser test content** configuration page — this is where you'll import the JSON you exported a moment ago, configure where and how often the test runs, and name each step so on-call engineers can read run results at a glance.
 
 ![New Test](../../img/new-test.png)

content/en/ninja-workshops/4-synthetics-scripting/1-real-browser-test/3-import-json.md

@@ -3,18 +3,24 @@ title: 1.3 Import JSON
 weight: 3
 ---
 
-To begin configuring our test, we need to import the JSON that we exported from the Chrome DevTools Recorder. To enable the {{% button %}}**Import**{{% /button %}} button, we must first give our test a name e.g. **`<your initials>` - Online Boutique**.
+To begin configuring our test we need to import the JSON file we exported from the Chrome DevTools Recorder. Splunk Synthetic Monitoring understands the recorder's native JSON format directly, so there's no conversion step — the importer reads each recorded step and creates a corresponding synthetic-test step, preserving the selectors, viewport, and any asserted navigation events.
+
+To enable the {{% button %}}**Import**{{% /button %}} button, we must first give our test a name. Use the same convention as the recording — your initials followed by the journey, e.g. **`<your initials>` - Online Boutique**. Prefixing with initials makes it easy for trainers and teammates to find each other's work in a shared organisation.
 
 ![Import](../../img/import.png)
 
-Once the {{% button %}}**Import**{{% /button %}} button is enabled, click on it and either drop the JSON file that you exported from the Chrome DevTools Recorder or upload the file.
+Once the {{% button %}}**Import**{{% /button %}} button is enabled, click on it and either drop the JSON file that you exported from the Chrome DevTools Recorder, or browse for it.
 
 ![Import JSON](../../img/import-json.png)
 
-Once the JSON file has been uploaded, click on {{% button style="blue" %}}Continue to edit steps{{% /button %}}
+Once the JSON has been parsed, you'll see a green confirmation showing the number of steps imported. If you ever see a smaller number than you expected here, it usually means one of the recorded actions wasn't in a format the Synthetics importer recognised — re-recording that specific interaction usually resolves it.
+
+Click on {{% button style="blue" %}}Continue to edit steps{{% /button %}}.
 
 ![Import Complete](../../img/import-complete.png)
 
+The **Edit steps** view shows each imported step in order, with the action type, target selector, and any wait conditions. You can reorder, add, or remove steps from here — but we'll come back to that in a later section.
+
 ![Edit Steps](../../img/edit-steps.png)
 
-Before we make any edits to the test, let's first configure the settings, click on {{% button style="blue" %}}< Return to test{{% /button %}}
+Before we make any edits to the steps themselves, let's first configure the test's run-time settings — where it runs from, how often, and on what device. Click on {{% button style="blue" %}}< Return to test{{% /button %}}.

content/en/ninja-workshops/4-synthetics-scripting/1-real-browser-test/4-edit-test-settings.md

@@ -3,28 +3,61 @@ title: 1.4 Settings
 weight: 4
 ---
 
-The simple settings allow you to configure the basics of the test:
+Every setting on this page maps directly to a real-world tradeoff between coverage, cost, signal quality, and load on the system you're monitoring. Before clicking through, here's what each control actually controls and the rule of thumb for choosing a value.
 
-- **Name**: The name of the test (e.g. RWC - Online Boutique).
-- **Details**:
-  - **Locations**: The locations where the test will run from.
-  - **Device**: Emulate different devices and connection speeds. Also, the viewport will be adjusted to match the chosen device.
-  - **Frequency**: How often the test will run.
-  - **Round-robin**: If multiple locations are selected, the test will run from one location at a time, rather than all locations at once.
-  - **Active**: Set the test to active or inactive.
+## Name
 
-![Return to Test]For this workshop, we will configure the locations that we wish to monitor from. Click in the **Locations** field and you will be presented with a list of global locations (over 50 in total).
+The display name for the test — used everywhere in the UI, in alert messages, in linked dashboards, and in detector titles. Bake context into it: include the service name, the journey, and (in shared organisations) your initials. **`<your initials>` - Online Boutique** works well for this workshop.
 
-![Global Locations](../../img/global-locations.png)
+## Locations
+
+The cloud regions Splunk runs the test from. There are over 50 to choose from, spread across all the major AWS regions. **Location choice matters more than people expect** because the metric you get back is the *measured* user experience from that location — network latency, TLS handshake time, and any geographic CDN routing are all baked in. A site that loads in 800 ms from N. Virginia might take 2.4 s from Mumbai if your CDN doesn't cache there.
+
+Best practice: pick locations that match where your real users live. If you have a US-east customer base and a separate EMEA customer base, monitor from both — and add at least one location that's *far* from any user (e.g. Melbourne for a US-only product) as an early-warning canary for global routing or DNS issues.
 
-Select the following locations:
+For this workshop we'll use three locations spanning three continents:
 
 - **AWS - N. Virginia**
 - **AWS - London**
 - **AWS - Melbourne**
 
-Once complete, scroll down and click on Click on {{% button style="blue" %}}Submit{{% /button %}} to save the test.
+Click in the **Locations** field and select each from the dropdown.
+
+![Global Locations](../../img/global-locations.png)
+
+## Device
+
+Emulates a specific device profile, which sets the viewport dimensions, user agent string, and a *throttled* CPU and network profile that approximates that device. The viewport stays consistent regardless of which location the test runs from.
+
+Why this matters: a fast-3G-throttled iPhone X with 4× CPU slowdown will surface real-user pain that an unthrottled desktop test would mask entirely. If your users are mostly on mobile, monitor on mobile.
+
+## Frequency
+
+How often the test runs from each location. The shorter the interval, the faster you'll catch a regression — but the more capacity you'll burn through and the more load you'll apply to the target site. Pick the lowest frequency that still gives your detectors a useful signal:
+
+| Frequency | Typical use |
+| --- | --- |
+| 1 min | Critical user journeys for high-traffic, high-revenue sites |
+| 5 min | Default for most production journeys (this workshop's setting) |
+| 10–15 min | Pre-prod, staging, lower-priority flows |
+| 30–60 min | Marketing pages, low-change static content |
+
+Remember the alert math: a 5-minute frequency means it can take **up to 5 minutes** to *first* detect a regression, and most detectors require 2–3 consecutive failures to fire — so a 5-minute test may not alert for 10–15 minutes after an incident begins.
+
+## Round-robin
+
+If you've selected multiple locations, **round-robin** changes how they're scheduled. Off (the default) means all selected locations run on every interval — three locations × every 5 minutes = 36 runs/hour. On means Splunk rotates through the locations, running one per interval — three locations × every 5 minutes = 12 runs/hour, but each individual location is now only sampled every 15 minutes.
+
+The tradeoff: round-robin slashes your run consumption and applies less load to the target, but dilutes per-location signal (so location-specific regressions are slower to surface). Leave it off for this workshop.
+
+## Active
+
+Toggles the test on or off. Leave it on. You can disable it later from the test list if you no longer want the run history accumulating.
+
+---
+
+Once you've set the name and selected the three locations, scroll down and click {{% button style="blue" %}}Submit{{% /button %}} to save the test.
 
-The test will now be scheduled to run every 5 minutes from the 3 locations that we have selected. This does take a few minutes for the schedule to be created.
+The test is now scheduled to run every 5 minutes from N. Virginia, London, and Melbourne. The first run usually takes a couple of minutes to dispatch — the scheduler has to allocate a browser slot in each region — so don't worry if you don't see results immediately.
 
-So whilst we wait for the test to be scheduled, click on {{% button %}}Edit test{{% /button %}} so we can go through the Advanced settings.
+While we wait, click on {{% button %}}Edit test{{% /button %}} so we can take a look at the **Advanced** settings.

content/en/ninja-workshops/4-synthetics-scripting/1-real-browser-test/5-advanced-settings.md

@@ -3,20 +3,25 @@ title: 1.5 Advanced Settings
 weight: 5
 ---
 
-Click on **Advanced**, these settings are optional and can be used to further configure the test.
+The default settings are enough for most public, unauthenticated journeys — but real production sites often need at least one of the controls under **Advanced**. We're not going to set any of them for this workshop, but it's worth knowing what each one is for so you can reach for the right tool later.
+
+Click on **Advanced** to expand the panel.
 
 {{% notice note %}}
 In the case of this workshop, we will **not** be using any of these settings as this is for informational purposes only.
 {{% /notice %}}
 
 ![Advanced Settings](../../img/advanced-settings.png)
 
-- **Security**:
-  - **TLS/SSL validation**: When activated, this feature is used to enforce the validation of expired, invalid hostname, or untrusted issuer on SSL/TLS certificates.
-  - **Authentication**: Add credentials to authenticate with sites that require additional security protocols, for example from within a corporate network. By using [concealed global variables](https://docs.splunk.com/Observability/synthetics/test-config/global-variables.html) in the Authentication field, you create an additional layer of security for your credentials and simplify the ability to share credentials across checks.
-- **Custom Content**:
-  - **Custom headers**: Specify custom headers to send with each request. For example, you can add a header in your request to filter out requests from analytics on the back end by sending a specific header in the requests. You can also use custom headers to set cookies.
-  - **Cookies**: Set cookies in the browser before the test starts. For example, to prevent a popup modal from randomly appearing and interfering with your test, you can set cookies. Any cookies that are set will apply to the domain of the starting URL of the check. Splunk Synthetics Monitoring uses the public suffix list to determine the domain.
-  - **Host overrides**: Add host override rules to reroute requests from one host to another. For example, you can create a host override to test an existing production site against page resources loaded from a development site or a specific CDN edge node.
+## Security
+
+- **TLS/SSL validation** — when activated, this enforces validation of certificate expiry, hostname mismatch, and untrusted issuer chains. Turning this *off* is sometimes necessary for testing against staging environments with self-signed certificates, but you should never leave it off for a production test — it disables one of the cheapest early-warning signals you have for certificate-related outages.
+- **Authentication** — credentials sent with every request, useful for sites behind HTTP Basic auth (still common on internal tooling and pre-prod environments). Store the credentials as [concealed global variables](https://docs.splunk.com/Observability/synthetics/test-config/global-variables.html) rather than typing them inline — concealed values aren't visible to anyone reading the test config, and they can be rotated in one place without editing every test that uses them.
+
+## Custom Content
+
+- **Custom headers** — extra headers sent on every request the test makes. Common uses: an `X-Synthetics: true` (or similar) header that your backend can use to exclude synthetic traffic from analytics dashboards and from RUM aggregations; a `Cache-Control: no-cache` header to test cold-cache performance; an A/B test cookie or feature-flag override header to pin the test to a specific variant.
+- **Cookies** — set in the browser *before* the test starts. The classic use case is suppressing a one-time-only modal (cookie banner, "subscribe to our newsletter" popup) that would otherwise occlude an element the test needs to click. Cookies are scoped to the domain of the starting URL, with Splunk Synthetic Monitoring using the [public suffix list](https://publicsuffix.org/) to determine the registrable domain.
+- **Host overrides** — reroute requests from one host to another at DNS-resolution time. Two common patterns: testing a production URL against a CDN edge node you're about to promote (override `www.example.com` to a specific edge IP); or running a production-shaped test against staging-shaped backends (override `api.example.com` to `api-staging.example.com`) without rewriting every step in the journey.
 
-Next, we will edit the test steps to provide more meaningful names for each step.
+Next, we'll edit the test steps to give each one a meaningful name — which becomes important the moment a step starts failing and a teammate has to read the alert.