[synthetics] Document the new Synthetics Recorder (#1953) (#2029)

* initial structure, connection to instructional content

add to index

* first full draft

* clean up text

* update docs/en/observability/synthetics-recorder.asciidoc

* address latest feedback

* add heading ids

* add beta note

* add image

(cherry picked from commit cdcffaf)

Co-authored-by: Colleen McGinnis <[email protected]>

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,21 @@ 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[]
+
+If you want to generate code by interacting with a web page directly, you can use the Synthetics Recorder.
+
+The recorder launches a https://www.chromium.org/Home/[Chromium browser] that will listen to each interaction you have with the web page and record them internally using Playwright.
+When you're done interacting with the browser, the recorder converts the recorded actions into JavaScript code that you can use with Elastic Synthetics or {heartbeat}.
+
+For more details on getting started with the Synthetics Recorder, see <<synthetics-recorder>>.
+
+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,138 @@
+[[synthetics-recorder]]
+= Synthetics Recorder
+
+beta[]
+
+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.
+
+image::images/synthetics-create-test-script-recorder.png[Elastic Synthetics Recorder after recording a journey and clicking Export]
+
+[discrete]
+[[synthetics-recorder-set-up]]
+== Set up
+
+Download and install the Elastic Synthetics Recorder from the https://github.com/elastic/synthetics-recorder/releases[GitHub repository's release page].
+
+[discrete]
+[[synthetics-recorder-record-a-journey]]
+== 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.
+
+[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]
+[[synthetics-recorder-name-steps]]
+=== 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]
+[[synthetics-recorder-split-into-multiple-steps]]
+=== 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]
+[[synthetics-recorder-edit-or-delete-recorded-actions]]
+=== 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]
+[[synthetics-recorder-add-assertions]]
+=== 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.
+As the test runs, 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]
+[[synthetics-recorder-export]]
+== 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.
+
+You can also check **Export as project** and either copy and paste or **Export**
+to get the full journey code including `journey` and imports for all dependencies. 
+
+[discrete]
+[[synthetics-recorder-next-steps]]
+== Next steps
+
+After you've refined your journey and exported it, use it to <<synthetics-manage-monitors, create a monitor>>.