[synthetics] Document the new Synthetics Recorder

docs/en/observability/index.asciidoc

@@ -114,6 +114,8 @@ include::synthetics-params-secrets.asciidoc[leveloffset=+3]
 
 include::synthetics-configuration.asciidoc[leveloffset=+3]
 
+include::synthetics-recorder.asciidoc[leveloffset=+3]
+
 include::synthetics-visualize.asciidoc[leveloffset=+3]
 
 include::uptime-analyze.asciidoc[leveloffset=+2]

docs/en/observability/synthetics-create-test.asciidoc

@@ -159,6 +159,26 @@ See the https://playwright.dev/docs/api/class-page#page-get-attribute[`page.getA
 <2> Use the assertion library provided by the Synthetics agent to look for the
 expected value. See https://jestjs.io/docs/expect[Jest expect docs] for more information.
 
+[discrete]
+[[synthetics-create-test-script-recorder]]
+=== Synthetics Recorder
+
+beta[]
+
+// In what circumstances should you use Synthetics Recorder?
+Use the Synthetics Recorder to generate code for one or more steps by interacting with a web page directly.
+
+// Some high-level details on what it does
+The recorder launches a special https://www.chromium.org/Home/[Chromium browser] that will listen to each interaction you have with the web page and record them internally.
+When you're done interacting with the page, the recorder converts the recorded actions into usable JavaScript code.
+Then you can copy or export the code to a file to use directly with Elastic Synthetics or {heartbeat}.
+// or upload the code to Kibana for use with the Synthetics Service.
+
+For more details on getting started with the Synthetics Recorder, see <<synthetics-recorder>>.
+
+// Maybe an image or two?
+image::images/synthetics-create-test-script-recorder.png[Elastic Synthetics Recorder after recording a journey and clicking Export]
+
 [discrete]
 [[before-after]]
 == Set up and remove a global state

docs/en/observability/synthetics-journeys.asciidoc

@@ -21,6 +21,7 @@ Then explore more synthetic monitoring topics to get the most out of your tests,
 * <<synthetics-params-secrets>>
 * <<synthetics-configuration>>
 * <<synthetics-command-reference>>
+* <<synthetics-recorder>>
 
 Finally, learn how to view and interpret data from your synthetic monitors in the {uptime-app}:
 

docs/en/observability/synthetics-recorder.asciidoc

@@ -0,0 +1,144 @@
+// Content type: Reference(ish)
+//
+// Purpose: Provide complete overview of the Synthetics Recorder UI.
+//
+// Structure: Reflects the pieces of the UI. Also somewhat sequential.
+//
+// Audience assumptions:
+// - The reader may or may not be familiar with Elastic Synthetics already.
+// - The reader might have come here from "Write a synthetic test" or they might have
+// arrived here from a search without larger no context.
+// - The reader might be using Project monitors, Heartbeat, or Elastic Agent.
+// 
+// What's not included:
+// - Detailed definitions of journey, step, etc.
+// - Detailed instructions on how to create a monitor. Point to instructional guide instead.
+
+[[synthetics-recorder]]
+= Synthetics Recorder
+
+You can use the Synthetics Recorder to <<synthetics-create-test, write a synthetic test>> by interacting with a web page and exporting journey code that reflects all the actions you took.
+
+[discrete]
+== Set up
+
+Download and install the Elastic Synthetics Recorder from the https://github.com/elastic/synthetics-recorder/releases[GitHub repository's release page].
+
+[discrete]
+== Record a journey
+
+To record a journey:
+
+. Enter a starting URL in the search box. This URL will be the starting point of the journey script the recorder will create.
+. Click **Start** or press Enter on your keyboard. This will launch a Chromium window open to the page you specified and start recording.
+. Start interacting with the browser. This can include clicking on text, navigation, focusing on inputs like buttons and text fields, and more.
+  . (Optional) You can click **Pause** to temporarily stop recording actions while you continue to interact with the browser. Click again to start recording actions again. Note: It's especially important to <<synthetics-recorder-test-the-journey, test the journey>> if you paused recording at any point.
+. When you're done interacting with the browser window, click **Stop** or close the browser to stop recording.
+// . As you complete your journey, you will see the actions you are generating populate in the Script Recorder's window.
+
+[discrete]
+[[synthetics-recorder-edit-a-journey]]
+== Edit a journey
+
+Once you've started recording, you can use the Synthetics Recorder UI to edit steps and individual actions before generating the journey code.
+You can also edit the journey after you've stopped recording.
+
+[discrete]
+=== Name steps
+
+Naming steps can help make the resulting journey code easier to understand.
+If you provide a step name, the name will be used in both the UI and the resulting code.
+If you don't name steps, the UI will show "Step 1", "Step 2", and so on, and the resulting code will use the first action in the step as the step text.
+
+To edit a step name:
+
+. Hover over the current step name and click the pencil icon that appears.
+. Edit the text in the text box.
+. Click Return or Enter on your keyboard to save the updated name.
+
+[discrete]
+=== Split into multiple steps
+
+Steps represent groups of actions that should be completed in a specific order.
+Breaking a journey into steps can make it easier to read the resulting code.
+It can also make it easier to interpret results in the {uptime-app} since each step is
+displayed individually in the {uptime-app} along with screenshots for convenient debugging and error tracking.
+
+By default, the Synthetics Recorder will group all actions in a single step,
+but you can break actions into any number of steps.
+
+To add a step:
+
+. Click the plus icon between two actions to create a new step.
+. (Optional) Consider naming the step.
+
+Use the trash can icon to delete the step divider, adding the actions from the deleted step into the previous step.
+
+[discrete]
+=== Edit or delete recorded actions
+
+You can fine-tune a journey by editing actions that were generated by the recorder.
+You can't change the type of command (for example, "click" or "navigate"), but you can change the value that is passed to the command.
+
+To edit an action:
+
+. Hover over an action and click the pencil icon that appears.
+. Edit the value as needed.
+. Click **Save**.
+
+To delete an action:
+
+. Hover over the action you want to delete and click the three dots for more options.
+. Click **Delete action**.
+
+IMPORTANT: If you changed or deleted any actions to ensure the journey still works, it's especially important to <<synthetics-recorder-test-the-journey, test the journey>>.
+
+[discrete]
+=== Add assertions
+
+Assertions can play an important role in effective synthetic journeys by making determinations about the state of the page you are testing.
+This can include checking if an element is visible or checking the contents of a text field.
+You can't generate an assertion just from interacting with the browser window.
+Instead, you can add assertions between generated actions.
+
+To add an assertion:
+
+. Find the generated action that should be done right before you want to assert a condition.
+. Hover over that action and click the three dots for more options.
+. Click **Add assertion**. This will add a new "assert" action in the UI.
+. Provide the type of assertion, selector, and value.
+. Click **Save**.
+
+IMPORTANT: If you added any assertions after you've finished recording to ensure the journey still works, it's especially important to <<synthetics-recorder-test-the-journey, test the journey>>.
+
+[discrete]
+[[synthetics-recorder-test-the-journey]]
+== Test the journey
+
+At any point during or after the recording process concludes, you can test your script.
+
+When you click the **Test** button, Elastic Synthetics will run the journey.
+After the test concludes, the recorder will display results on a per-step basis.
+If there are any errors that prevent the journey from running, the recorder will display the relevant error message to help you debug.
+
+IMPORTANT: If you paused recording, updated actions, or added assertions manually in the recorder it is especially important that you test the journey to  verify that the actions work in sequence.
+
+[discrete]
+== Export
+
+When you are satisfied with journey you've created, you can export it from the recorder.
+
+Click **Export** to view the final journey code.
+From there you can use the code by:
+
+* Copy and pasting code containing all steps into a new or existing <<synthetic-monitor-choose-project, synthetics project>> or an <<synthetics-inline-journey, inline monitor>>.
+* Click **Export** to save a JavaScript file containing all steps.
+
+// suite --> project?
+You can also check **Export as a suite** and either copy and paste or **Export**
+to get the full journey code including `journey` and imports for all dependencies. 
+
+[discrete]
+== Next steps
+
+After you've refined your journey and exported it, use it to <<synthetics-manage-monitors, create a monitor>>.