Skip to content

Commit b5236c3

Browse files
mdmintzmdmintz
committed
Update the docs
1 parent aedf06e commit b5236c3

File tree

4 files changed

+71
-49
lines changed

4 files changed

+71
-49
lines changed

‎README.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -108,7 +108,7 @@ COMMANDS:
108108
options (List common pytest options)
109109
mkdir [DIRECTORY] [OPTIONS]
110110
mkfile [FILE.py] [OPTIONS]
111-
mkrec / codegen [FILE.py]
111+
mkrec / codegen [FILE.py] [OPTIONS]
112112
mkpres [FILE.py] [LANG]
113113
mkchart [FILE.py] [LANG]
114114
print [FILE] [OPTIONS]

‎help_docs/recorder_mode.md

Lines changed: 58 additions & 42 deletions
Original file line numberDiff line numberDiff line change
@@ -2,83 +2,99 @@
22

33
<h2><img src="https://seleniumbase.io/img/logo6.png" title="SeleniumBase" width="32" /> Recorder Mode</h2>
44

5-
🔴 <b>SeleniumBase Recorder Mode</b> lets you record & export browser actions into automation scripts.<br>
5+
🔴 <b>SeleniumBase Recorder Mode</b> lets you record & export browser actions into test automation scripts.<br>
66

77
<img src="https://seleniumbase.io/cdn/img/sb_recorder_notification.png" title="SeleniumBase" width="380">
88

9-
🔴 To activate Recorder Mode, add ``--rec`` OR ``--record`` OR ``--recorder`` to your ``pytest`` run command when running an existing test on Chrome or Edge. (Also add ``-s`` to allow breakpoints, unless you already have a ``pytest.ini`` file present with ``addopts = --capture=no`` in it.)
9+
(This tutorial assumes you are using SeleniumBase version ``2.0.8`` or newer.)
10+
11+
🔴 To make a new recording with Recorder Mode, you can use ``sbase mkrec`` or ``sbase codegen``):
1012

1113
```bash
12-
pytest TEST_NAME.py --rec -s
14+
sbase mkrec TEST_NAME.py --url=URL
1315
```
1416

15-
🔴 To add manual actions, you'll need to create a breakpoint inside your test to activate "Debug Mode" while in "Recorder Mode": (For reference, "Debug Mode" is also known as the "ipdb debugger".)
16-
17-
```python
18-
import ipdb; ipdb.set_trace()
19-
```
17+
If the file already exists, you'll get an error. If no URL is provided, you'll start on a blank page and will need to navigate somewhere for the Recorder to activate. (The Recorder captures events on URLs that start with ``https``, ``http``, or ``file``.) The command above runs an empty test that stops at a breakpoint so that you can perform manual browser actions for the Recorder. When you have finished recording, type "``c``" on the command-line and press ``[ENTER]`` to let the test continue from the breakpoint. The test will then complete and a file called ``TEST_NAME_rec.py`` will be automatically created in the ``./recordings`` folder. That file will get copied back to the original folder with the name you gave it. (You can run with Edge instead of Chrome by adding ``--edge`` to the command above.)
2018

21-
🔴 You can also activate Debug Mode at the start of your test by adding ``--trace`` as a ``pytest`` command-line option: (This is useful when running Recorder Mode without any breakpoints.)
19+
Example:
2220

2321
```bash
24-
pytest TEST_NAME.py --trace --rec -s
25-
```
22+
sbase mkrec new_test.py --url=wikipedia.org
2623

27-
🔴 Once you've reached the breakpoint, you can take control of the browser and add in any actions that you want recorded. The Recorder will capture browser actions on URLs that begin with ``https:``, ``http:``, and ``file:``; (the Recorder won't work on ``data:`` URLS). When you are finished recording, type "``c``" on the command-line and press ``[Enter]`` to let the test continue from the breakpoint. After the test completes, a file called ``TEST_NAME_rec.py`` will be automatically created in the ``./recordings`` folder, which will include the actions performed by the test, and the manual actions that you added in. Below is a command-line notification:
24+
* RECORDING initialized: new_test.py
2825

29-
```bash
30-
>>> RECORDING SAVED as: recordings/my_first_test_rec.py
31-
*******************************************************
32-
```
26+
pytest new_test.py --rec -q -s --url=wikipedia.org
3327

34-
🔴 If running tests from one module, recordings will share a file:
28+
> .../SeleniumBase/examples/new_test.py(7)test_recording()
29+
5 def test_recording(self):
30+
6 if self.recorder_ext and not self.xvfb:
31+
----> 7 import ipdb; ipdb.set_trace()
3532

36-
```bash
37-
>>> RECORDING ADDED to: recordings/my_first_test_rec.py
38-
*******************************************************
33+
ipdb> c
34+
35+
>>> RECORDING SAVED as: recordings/new_test_rec.py
36+
**************************************************
37+
38+
*** RECORDING COPIED to: new_test.py
3939
```
4040
41-
🔴 While a recording is in progress, you can hit the ``[ESC]`` key to pause the recording. To resume the recording, you can hit the ``[~`]`` key, which is located directly below the ``[ESC]`` key on most keyboards.
41+
🔴 While a recording is in progress, you can press the ``[ESC]`` key to pause the recording. To resume the recording, you can hit the ``[~`]`` key, which is located directly below the ``[ESC]`` key on most keyboards.
4242
43-
<p>🔴 If you want to create a recording from scratch, just run:<br><code>pytest --rec</code> on a Python file such as this one:</p>
43+
🔴 From within Recorder Mode there are two additional modes: "Assert Element Mode" and "Assert Text Mode". To switch into "Assert Element Mode", press the <code>{^}-key (SHIFT+6)</code>: The border will become purple, and you'll be able to click on elements to assert from your test. To switch into "Assert Text Mode", press the <code>{&}-key (SHIFT+7)</code>: The border will become teal, and you'll be able to click on elements for asserting text from your test. While using either of the two special Assertion Modes, certain actions such as clicking on links won't have any effect. This lets you make assertions on elements without navigating away from the page, etc. To return back to the original Recorder Mode, press any key other than SHIFT or BACKSPACE (Eg: Press ``CONTROL``, etc.). You can also press ESC once to leave the Assertion Modes, but if you press it again, it'll stop the Recorder.
4444
45-
```python
46-
from seleniumbase import BaseCase
45+
🔴 For extra flexibility, you can break up the ``sbase mkrec`` command into three separate commands so that you can pick & choose how you use the Recorder:
46+
47+
```bash
48+
sbase mkfile TEST_NAME.py --rec
4749
48-
class RecorderTest(BaseCase):
49-
def test_recorder(self):
50-
import ipdb; ipdb.set_trace()
50+
pytest TEST_NAME.py --rec -q -s
51+
52+
cp ./recordings/TEST_NAME_rec.py ./TEST_NAME.py
5153
```
5254
53-
<p>🔴 The above code gives you a basic SeleniumBase file with a breakpoint in it so that you can immediately start recording after you've opened a new web page in the browser.</p>
55+
The first command creates a boilerplate test with a breakpoint; the second command runs the test with the Recorder activated; and the third command replaces the initial boilerplate with the full recorded test. If you're just experimenting with the Recorder, you can run the second command as many times as you want, and it'll override previous recordings saved to ``./recordings/TEST_NAME_rec.py``. (Note that ``-s`` is needed to allow breakpoints, unless you already have a ``pytest.ini`` file present with ``addopts = --capture=no`` in it. The ``-q`` is optional, which shortens ``pytest`` console output.)
5456
55-
<p>🔴 Recorder Mode works by saving your recorded actions into the browser's <code>sessionStorage</code>. SeleniumBase then reads from the browser's <code>sessionStorage</code> to take the raw data and generate a full test from it. Keep in mind that <code>sessionStorage</code> is only present for a website while the browser tab remains on a web page of the same domain/origin. If you leave that domain/origin, the <code>sessionStorage</code> of that tab will no longer have the raw data that SeleniumBase needs to create a full recording. To compensate for this, all links to web pages of a different domain/origin will automatically open a new tab for you while in Recorder Mode. Additionally, the SeleniumBase <code>self.open(URL)</code> method will also open a new tab for you in Recorder Mode if the domain/origin is different from the current URL. When the recorded test completes, SeleniumBase will scan the <code>sessionStorage</code> of all open browser tabs for the data it needs to generate the complete SeleniumBase automation script.</p>
57+
🔴 You can also use the Recorder to add code to an existing test. To do that, you'll first need to create a breakpoint in your code where you want to insert manual browser actions:
5658
57-
<p>🔴 If you just want to record actions on a single URL of a multi-URL test, you can call <code>self.activate_recorder()</code> from within the test instead of using <code>pytest --rec</code> from the command-line. When doing so, make sure that the browser tab is still on the same domain/origin at the end of the test, or else SeleniumBase will not have access to the <code>sessionStorage</code> data that it needs for generating a complete test.</p>
59+
```python
60+
import ipdb; ipdb.set_trace()
61+
```
5862
59-
<p>🔴 (Note that <b>same domain/origin</b> is not the same as <b>same URL</b>. Example: <code>https://xkcd.com/353/</code> and <code>https://xkcd.com/1537/</code> are two different URLs with the <b>same domain/origin</b>. That means that both URLs will share the same <code>sessionStorage</code> data, and that any changes to <code>sessionStorage</code> from one URL will carry on to the <code>sessionStorage</code> of a different URL when the domain/origin is the same. If you want to find out a website's origin during a test, just call: <code>self.get_origin()</code>, which returns the value of <code>window.location.origin</code> from the browser's console.)</p>
63+
Now you'll be able to run your test with ``pytest``, and it will stop at the breakpoint for you to add in actions: (Press ``c`` and ``ENTER`` on the command-line to continue from the breakpoint.)
6064
61-
<p>🔴 The launch of Recorder Mode has brought a new SeleniumBase method along with it: <code>self.open_if_not_url(URL)</code>. This method will open the URL given if the browser is not currently on that page. This is used as a method in recorded scripts when SeleniumBase detects that a click action has already brought the test to the given page. This method not only prevents an extra page load if not needed, but it also lets people know the current page of the browser during that part of the test.</p>
65+
```bash
66+
pytest TEST_NAME.py --rec -s
67+
```
6268
63-
<p>🔴 SeleniumBase <code>1.66.1</code> adds the ability to record changes to <i>"Choose File"</i> <code>input</code> fields. Sometimes the <i>"Choose File"</i> input field is hidden on websites, so <code>self.show_file_choosers()</code> was added to get around this edge case. Version <code>1.66.1</code> also adds <code>self.set_content_to_frame(frame)</code>, which lets you record actions inside of iframes.</p>
69+
🔴 You can also set a breakpoint at the start of your test by adding ``--trace`` as a ``pytest`` command-line option: (This is useful when running Recorder Mode without any ``ipdb`` breakpoints.)
6470
65-
<p>🔴 SeleniumBase <code>1.66.2</code> adds the ability to save selectors using the <code>":contains(TEXT)"</code> selector. If a Python file being recorded has multiple tests being run, then all those tests will get saved to the generated <code>*_rec.py</code> file. The Recorder will now save common <code>self.assert_*</code> calls made during tests. In order to escape iframes when using <code>self.set_content_to_frame(frame)</code>, a new method was added: <code>self.set_content_to_default()</code>. The <code>self.set_content_to_*()</code> methods will be automatically used in place of <code>self.switch_to_*()</code> methods in Recorder Mode, unless a test explicitly calls <code>self._rec_overrides_switch = False</code> before the <code>self.switch_to_*()</code> methods are called. Additionally, if an iframe contains the <code>src</code> attribute, that page will get loaded in a new tab when switching to it in Recorder Mode.</p>
71+
```bash
72+
pytest TEST_NAME.py --trace --rec -s
73+
```
6674
67-
<p>🔴 SeleniumBase versions <code>1.66.3</code>, <code>1.66.4</code>, <code>1.66.5</code>, <code>1.66.6</code>, <code>1.66.7</code>, <code>1.66.8</code>, and <code>1.66.9</code> improve the algorithm for converting recorded actions into SeleniumBase code.</p>
75+
🔴 After the test completes, a file called ``TEST_NAME_rec.py`` will be automatically created in the ``./recordings`` folder, which will include the actions performed by the test, and the manual actions that you added in.
6876
69-
<p>🔴 SeleniumBase <code>1.66.10</code> adds better error-handling to the Recorder. It also adds the console script option <code>-r</code> for <code>sbase mkfile</code> to generate a new test file with a breakpoint for Recorder Mode: <code>sbase mkfile NEW_FILE.py -r</code></p>
77+
🔴 Here's a command-line notification for a completed recording:
7078
71-
<p>🔴 SeleniumBase <code>1.66.12</code> adds the ability to instantly create a new test recording by running <code>sbase mkrec FILE.py</code>. Once the browser spins up, you can open a new web page and start performing actions that will get recorded and saved to the file you specified.</p>
79+
```bash
80+
>>> RECORDING SAVED as: recordings/TEST_NAME_rec.py
81+
***************************************************
82+
```
7283
73-
<p>🔴 SeleniumBase <code>1.66.13</code> lets you add assertions for elements and text while making a recording. To add an element assertion, press the <code>{^}-key (SHIFT+6)</code>, (the border will become purple) then click on elements that you'd like to assert. To add a text assertion, press the <code>{&}-key (SHIFT+7)</code>, (the border will become orange) then click on text elements that you'd like to assert. To go back to the regular Record Mode, press any other key. While in the special assertion modes, certain actions such as clicking on links won't have any effect. This lets you make assertions on elements without certain actions getting in the way.</p>
84+
🔴 When running additional tests from the same Python module, Recordings will get added to the file that was created from the first test:
85+
86+
```bash
87+
>>> RECORDING ADDED to: recordings/TEST_NAME_rec.py
88+
***************************************************
89+
```
7490
75-
<p>🔴 SeleniumBase <code>1.66.14</code> improves the algorithm for converting recorded assertions into SeleniumBase code. Text assertions that contain the newline character will now be handled correctly. If a text assertion has a <code>:contains</code> selector, then the text assertion will be changed to an element assertion. Asserted text from multi-line assertions will use <code>self.assert_text()</code> on the first non-empty line. Asserted text from single-line assertions will use <code>self.assert_exact_text()</code>. Element assertions will be handled with <code>self.assert_element()</code>.</p>
91+
🔴 Recorder Mode works by saving your recorded actions into the browser's <code>sessionStorage</code>. SeleniumBase then reads from the browser's <code>sessionStorage</code> to take the raw data and generate a full test from it. Keep in mind that <code>sessionStorage</code> is only present for a website while the browser tab remains on a web page of the same domain/origin. If you leave that domain/origin, the <code>sessionStorage</code> of that tab will no longer have the raw data that SeleniumBase needs to create a full recording. To compensate for this, all links to web pages of a different domain/origin will automatically open a new tab for you while in Recorder Mode. Additionally, the SeleniumBase <code>self.open(URL)</code> method will also open a new tab for you in Recorder Mode if the domain/origin is different from the current URL. When the recorded test completes, SeleniumBase will scan the <code>sessionStorage</code> of all open browser tabs for the data it needs to generate the complete SeleniumBase automation script.
7692
77-
<p>🔴 SeleniumBase <code>2.0.1</code> adds the ability to preview selectors via the page title when hovering over elements. It also fixes an issue that may occur when opening up new URLs while in Recorder Mode.</p>
93+
🔴 As an alternative to activating Recorder Mode with the <code>--rec</code> command-line arg, you can also call <code>self.activate_recorder()</code> from your tests. This is only useful for tests that stay on the same URL because the Recorder will turn off when leaving the page where you activated the Recorder. The reason for this is because the standard Recorder Mode functions as a Chrome extension (and persists wherever the browser goes), whereas the method call version of Recorder Mode only lives in the page where it was called.
7894
79-
<p>🔴 SeleniumBase <code>2.0.2</code> fixes a bug with Recorder Mode that was preventing the last recorded assert on a domain from being saved unless it was followed by a non-assert recorded action on the same domain.</p>
95+
🔴 (Note that <b>same domain/origin</b> is not the same as <b>same URL</b>. Example: <code>https://xkcd.com/353/</code> and <code>https://xkcd.com/1537/</code> are two different URLs with the <b>same domain/origin</b>. That means that both URLs will share the same <code>sessionStorage</code> data, and that any changes to <code>sessionStorage</code> from one URL will carry on to the <code>sessionStorage</code> of a different URL when the domain/origin is the same. If you want to find out a website's origin during a test, just call: <code>self.get_origin()</code>, which returns the value of <code>window.location.origin</code> from the browser's console.)
8096
81-
<p>🔴 SeleniumBase <code>2.0.4</code> lets you go back to regular Recorder Mode from Assert Mode by pressing [ESC] once. If you press it again, it will pause the Recorder. (Previously, pressing [ESC] would pause the Recorder right away if using Assert Mode). As before, pressing the <code>{^}-key (SHIFT+6)</code> will switch the Recorder into Assert Element Mode and pressing the <code>{&}-key (SHIFT+7)</code> will switch the Recorder into Assert Text Mode. You can switch back to regular Recorder Mode from Assert Mode by pressing any key other than [SHIFT] and [BACKSPACE]. Also, <code>--codegen</code> can be used in place of <code>--recorder</code> for Recorder initialization, and <code>sbase codegen [FILE.py]</code> can be used in place of <code>sbase mkrec [FILE.py]</code>, which calls attention to the code-generation abilities of the Recorder.</p>
97+
🔴 Inside recorded tests, you might find the <code>self.open_if_not_url(URL)</code> method, which opens the URL given if the browser is not currently on that page. This is used as a method in recorded scripts when SeleniumBase detects that a browser action (such as a click) has brought the test to that page. This method not only prevents an extra page load if not needed, but it also lets people know what page the test went to after a browser action was performed.
8298
8399
--------
84100

‎mkdocs_build/requirements.txt

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,12 @@
11
regex>=2021.10.23
22
tqdm>=4.62.3
3-
docutils==0.17.1
3+
docutils==0.18
44
python-dateutil==2.8.2
55
livereload==2.6.3;python_version>="3.6"
66
joblib==1.1.0;python_version>="3.6"
77
Markdown==3.3.4;python_version>="3.6"
88
MarkupSafe==2.0.1;python_version>="3.6"
9-
pyparsing==3.0.1;python_version>="3.6"
9+
pyparsing==3.0.3;python_version>="3.6"
1010
keyring==23.2.1;python_version>="3.6"
1111
pkginfo==1.7.1;python_version>="3.6"
1212
Jinja2==3.0.2;python_version>="3.6"
@@ -21,7 +21,7 @@ lunr==0.6.1;python_version>="3.6"
2121
nltk==3.6.5;python_version>="3.6"
2222
watchdog==2.1.6;python_version>="3.6"
2323
mkdocs==1.2.3;python_version>="3.6"
24-
mkdocs-material==7.3.4;python_version>="3.6"
24+
mkdocs-material==7.3.5;python_version>="3.6"
2525
mkdocs-exclude-search==0.5.2;python_version>="3.6"
2626
mkdocs-simple-hooks==0.1.3
2727
mkdocs-material-extensions==1.0.3;python_version>="3.6"

‎seleniumbase/console_scripts/ReadMe.md

Lines changed: 9 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,7 @@ COMMANDS:
1919
options (List common pytest options)
2020
mkdir [DIRECTORY] [OPTIONS]
2121
mkfile [FILE.py] [OPTIONS]
22-
mkrec / codegen [FILE.py]
22+
mkrec / codegen [FILE.py] [OPTIONS]
2323
mkpres [FILE.py] [LANG]
2424
mkchart [FILE.py] [LANG]
2525
print [FILE] [OPTIONS]
@@ -225,12 +225,18 @@ is included.
225225
<h3>mkrec / codegen</h3>
226226

227227
* Usage:
228-
``sbase mkrec [FILE.py]``
229-
``sbase codegen [FILE.py]``
228+
``sbase mkrec [FILE.py] [OPTIONS]``
229+
``sbase codegen [FILE.py] [OPTIONS]``
230230

231231
* Examples:
232232
``sbase mkrec new_test.py``
233+
``sbase mkrec new_test.py --url=seleniumbase.io``
233234
``sbase codegen new_test.py``
235+
``sbase codegen new_test.py --url=wikipedia.org``
236+
237+
* Options:
238+
``--url=URL`` (Sets the initial start page URL.)
239+
``--edge`` (Use Edge browser instead of Chrome.)
234240

235241
* Output:
236242
Creates a new SeleniumBase test using the Recorder.

0 commit comments

Comments
 (0)