Skip to content

Commit 916bdb1

Browse files
mdmintzmdmintz
committed
Update the docs
1 parent cc28be0 commit 916bdb1

File tree

1 file changed

+271
-1
lines changed

1 file changed

+271
-1
lines changed

‎help_docs/customizing_test_runs.md

Lines changed: 271 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,26 @@
11
<!-- SeleniumBase Docs -->
22

3-
## [<img src="https://seleniumbase.github.io/img/logo6.png" title="SeleniumBase" width="32">](https://github.com/seleniumbase/SeleniumBase/) pytest options for SeleniumBase
3+
<a id="customizing_test_runs"></a>
4+
5+
<h2><img src="https://seleniumbase.github.io/img/logo6.png" title="SeleniumBase" width="40"> Options / Customization</h2>
6+
7+
<h3>🎛️ SeleniumBase has different ways of setting options, depending on which format you're using. Options can be set via the command-line or method call.</h3>
8+
9+
<blockquote>
10+
<p dir="auto"></p>
11+
<ul dir="auto">
12+
<li><a href="#pytest_options"><strong>01. <code>pytest</code> command-line options</strong></a></li>
13+
<li><a href="#sb_options"><strong>02. <code>SB()</code> method options</strong></a></li>
14+
<li><a href="#driver_options"><strong>03. <code>Driver()</code> method options</strong></a></li>
15+
<li><a href="#sb_cdp_chrome_options"><strong>04. <code>sb_cdp.Chrome()</code> method options</strong></a></li>
16+
<li><a href="#activate_cdp_mode_options"><strong>05. <code>activate_cdp_mode()</code> method options</strong></a></li>
17+
</ul>
18+
</blockquote>
19+
20+
--------
21+
22+
<a id="pytest_options"></a>
23+
<h2><img src="https://seleniumbase.github.io/img/logo6.png" title="SeleniumBase" width="32" /> 01. <code>pytest</code> command-line options</h2>
424

525
🎛️ SeleniumBase's [pytest plugin](https://github.com/seleniumbase/SeleniumBase/blob/master/seleniumbase/plugins/pytest_plugin.py) lets you customize test runs from the CLI (Command-Line Interface), which adds options for setting/enabling the browser type, Dashboard Mode, Demo Mode, Headless Mode, Mobile Mode, Multi-threading Mode, Recorder Mode, UC Mode (stealth), reuse-session mode, Proxy Mode, and more.
626

@@ -604,4 +624,254 @@ pytest test_swag_labs.py --mobile --agent="Mozilla/5.0 (Linux; Android 9; Pixel
604624

605625
--------
606626

627+
<a id="sb_options"></a>
628+
<h2><img src="https://seleniumbase.github.io/img/logo6.png" title="SeleniumBase" width="32" /> 02. <code>SB()</code> method options</h2>
629+
630+
```python
631+
test=None # Test Mode: Output, Logging, Continue on failure unless "rtf".
632+
rtf=None # Shortcut / Duplicate of "raise_test_failure".
633+
raise_test_failure=None # If "test" mode, raise Exception on 1st failure.
634+
browser=None # Choose from "chrome", "edge", "firefox", or "safari".
635+
headless=None # Use the default headless mode for Chromium and Firefox.
636+
headless1=None # Use Chromium's old headless mode. (Fast, but limited)
637+
headless2=None # Use Chromium's new headless mode. (Has more features)
638+
locale_code=None # Set the Language Locale Code for the web browser.
639+
protocol=None # The Selenium Grid protocol: "http" or "https".
640+
servername=None # The Selenium Grid server/IP used for tests.
641+
port=None # The Selenium Grid port used by the test server.
642+
proxy=None # Use proxy. Format: "SERVER:PORT" or "USER:PASS@SERVER:PORT".
643+
proxy_bypass_list=None # Skip proxy when using the listed domains.
644+
proxy_pac_url=None # Use PAC file. (Format: URL or USERNAME:PASSWORD@URL)
645+
multi_proxy=None # Allow multiple proxies with auth when multi-threaded.
646+
agent=None # Modify the web browser's User-Agent string.
647+
cap_file=None # The desired capabilities to use with a Selenium Grid.
648+
cap_string=None # The desired capabilities to use with a Selenium Grid.
649+
recorder_ext=None # Enables the SeleniumBase Recorder Chromium extension.
650+
disable_cookies=None # Disable Cookies on websites. (Pages might break!)
651+
disable_js=None # Disable JavaScript on websites. (Pages might break!)
652+
disable_csp=None # Disable the Content Security Policy of websites.
653+
enable_ws=None # Enable Web Security on Chromium-based browsers.
654+
enable_sync=None # Enable "Chrome Sync" on websites.
655+
use_auto_ext=None # Use Chrome's automation extension.
656+
undetectable=None # Use undetected-chromedriver to evade bot-detection.
657+
uc_cdp_events=None # Capture CDP events in undetected-chromedriver mode.
658+
uc_subprocess=None # Use undetected-chromedriver as a subprocess.
659+
log_cdp_events=None # Capture {"performance": "ALL", "browser": "ALL"}
660+
incognito=None # Enable Chromium's Incognito mode.
661+
guest_mode=None # Enable Chromium's Guest mode.
662+
dark_mode=None # Enable Chromium's Dark mode.
663+
devtools=None # Open Chromium's DevTools when the browser opens.
664+
remote_debug=None # Enable Chrome's Debugger on "http://localhost:9222".
665+
enable_3d_apis=None # Enable WebGL and 3D APIs.
666+
swiftshader=None # Chrome: --use-gl=angle / --use-angle=swiftshader-webgl
667+
ad_block_on=None # Block some types of display ads from loading.
668+
host_resolver_rules=None # Set host-resolver-rules, comma-separated.
669+
block_images=None # Block images from loading during tests.
670+
do_not_track=None # Tell websites that you don't want to be tracked.
671+
chromium_arg=None # "ARG=N,ARG2" (Set Chromium args, ","-separated.)
672+
firefox_arg=None # "ARG=N,ARG2" (Set Firefox args, comma-separated.)
673+
firefox_pref=None # SET (Set Firefox PREFERENCE:VALUE set, ","-separated)
674+
user_data_dir=None # Set the Chrome user data directory to use.
675+
extension_zip=None # Load a Chrome Extension .zip|.crx, comma-separated.
676+
extension_dir=None # Load a Chrome Extension directory, comma-separated.
677+
disable_features=None # "F1,F2" (Disable Chrome features, ","-separated.)
678+
binary_location=None # Set path of the Chromium browser binary to use.
679+
driver_version=None # Set the chromedriver or uc_driver version to use.
680+
skip_js_waits=None # Skip JS Waits (readyState=="complete" and Angular).
681+
wait_for_angularjs=None # Wait for AngularJS to load after some actions.
682+
use_wire=None # Use selenium-wire's webdriver over selenium webdriver.
683+
external_pdf=None # Set Chrome "plugins.always_open_pdf_externally":True.
684+
window_position=None # Set the browser's starting window position: "X,Y"
685+
window_size=None # Set the browser's starting window size: "Width,Height"
686+
is_mobile=None # Use the mobile device emulator while running tests.
687+
mobile=None # Shortcut / Duplicate of "is_mobile".
688+
device_metrics=None # Set mobile metrics: "CSSWidth,CSSHeight,PixelRatio"
689+
xvfb=None # Run tests using the Xvfb virtual display server on Linux OS.
690+
xvfb_metrics=None # Set Xvfb display size on Linux: "Width,Height".
691+
start_page=None # The starting URL for the web browser when tests begin.
692+
rec_print=None # If Recorder is enabled, prints output after tests end.
693+
rec_behave=None # Like Recorder Mode, but also generates behave-gherkin.
694+
record_sleep=None # If Recorder enabled, also records self.sleep calls.
695+
data=None # Extra test data. Access with "self.data" in tests.
696+
var1=None # Extra test data. Access with "self.var1" in tests.
697+
var2=None # Extra test data. Access with "self.var2" in tests.
698+
var3=None # Extra test data. Access with "self.var3" in tests.
699+
variables=None # DICT (Extra test data. Access with "self.variables")
700+
account=None # Set account. Access with "self.account" in tests.
701+
environment=None # Set the test env. Access with "self.env" in tests.
702+
headed=None # Run tests in headed/GUI mode on Linux, where not default.
703+
maximize=None # Start tests with the browser window maximized.
704+
disable_ws=None # Reverse of "enable_ws". (None and False are different)
705+
disable_beforeunload=None # Disable the "beforeunload" event on Chromium.
706+
settings_file=None # A file for overriding default SeleniumBase settings.
707+
position=None # Shortcut / Duplicate of "window_position".
708+
size=None # Shortcut / Duplicate of "window_size".
709+
uc=None # Shortcut / Duplicate of "undetectable".
710+
undetected=None # Shortcut / Duplicate of "undetectable".
711+
uc_cdp=None # Shortcut / Duplicate of "uc_cdp_events".
712+
uc_sub=None # Shortcut / Duplicate of "uc_subprocess".
713+
locale=None # Shortcut / Duplicate of "locale_code".
714+
log_cdp=None # Shortcut / Duplicate of "log_cdp_events".
715+
ad_block=None # Shortcut / Duplicate of "ad_block_on".
716+
server=None # Shortcut / Duplicate of "servername".
717+
guest=None # Shortcut / Duplicate of "guest_mode".
718+
wire=None # Shortcut / Duplicate of "use_wire".
719+
pls=None # Shortcut / Duplicate of "page_load_strategy".
720+
sjw=None # Shortcut / Duplicate of "skip_js_waits".
721+
wfa=None # Shortcut / Duplicate of "wait_for_angularjs".
722+
cft=None # Use "Chrome for Testing"
723+
chs=None # Use "Chrome-Headless-Shell"
724+
save_screenshot=None # Save a screenshot at the end of each test.
725+
no_screenshot=None # No screenshots saved unless tests directly ask it.
726+
page_load_strategy=None # Set Chrome PLS to "normal", "eager", or "none".
727+
timeout_multiplier=None # Multiplies the default timeout values.
728+
js_checking_on=None # Check for JavaScript errors after page loads.
729+
slow=None # Slow down the automation. Faster than using Demo Mode.
730+
demo=None # Slow down and visually see test actions as they occur.
731+
demo_sleep=None # SECONDS (Set wait time after Slow & Demo Mode actions.)
732+
message_duration=None # SECONDS (The time length for Messenger alerts.)
733+
highlights=None # Number of highlight animations for Demo Mode actions.
734+
interval=None # SECONDS (Autoplay interval for SB Slides & Tour steps.)
735+
time_limit=None # SECONDS (Safely fail tests that exceed the time limit.)
736+
```
737+
738+
Example: [SeleniumBase/examples/raw_robot.py](https://github.com/seleniumbase/SeleniumBase/blob/master/examples/raw_robot.py)
739+
740+
--------
741+
742+
<a id="driver_options"></a>
743+
<h2><img src="https://seleniumbase.github.io/img/logo6.png" title="SeleniumBase" width="32" /> 03. <code>Driver()</code> method options</h2>
744+
745+
```python
746+
browser=None # Choose from "chrome", "edge", "firefox", or "safari".
747+
headless=None # Use the default headless mode for Chromium and Firefox.
748+
headless1=None # Use Chromium's old headless mode. (Fast, but limited)
749+
headless2=None # Use Chromium's new headless mode. (Has more features)
750+
headed=None # Run tests in headed/GUI mode on Linux, where not default.
751+
locale_code=None # Set the Language Locale Code for the web browser.
752+
protocol=None # The Selenium Grid protocol: "http" or "https".
753+
servername=None # The Selenium Grid server/IP used for tests.
754+
port=None # The Selenium Grid port used by the test server.
755+
proxy=None # Use proxy. Format: "SERVER:PORT" or "USER:PASS@SERVER:PORT".
756+
proxy_bypass_list=None # Skip proxy when using the listed domains.
757+
proxy_pac_url=None # Use PAC file. (Format: URL or USERNAME:PASSWORD@URL)
758+
multi_proxy=None # Allow multiple proxies with auth when multi-threaded.
759+
agent=None # Modify the web browser's User-Agent string.
760+
cap_file=None # The desired capabilities to use with a Selenium Grid.
761+
cap_string=None # The desired capabilities to use with a Selenium Grid.
762+
recorder_ext=None # Enables the SeleniumBase Recorder Chromium extension.
763+
disable_cookies=None # Disable Cookies on websites. (Pages might break!)
764+
disable_js=None # Disable JavaScript on websites. (Pages might break!)
765+
disable_csp=None # Disable the Content Security Policy of websites.
766+
enable_ws=None # Enable Web Security on Chromium-based browsers.
767+
disable_ws=None # Reverse of "enable_ws". (None and False are different)
768+
enable_sync=None # Enable "Chrome Sync" on websites.
769+
use_auto_ext=None # Use Chrome's automation extension.
770+
undetectable=None # Use undetected-chromedriver to evade bot-detection.
771+
uc_cdp_events=None # Capture CDP events in undetected-chromedriver mode.
772+
uc_subprocess=None # Use undetected-chromedriver as a subprocess.
773+
log_cdp_events=None # Capture {"performance": "ALL", "browser": "ALL"}
774+
no_sandbox=None # (DEPRECATED) - "--no-sandbox" is always used now.
775+
disable_gpu=None # (DEPRECATED) - GPU is disabled if not "swiftshader".
776+
incognito=None # Enable Chromium's Incognito mode.
777+
guest_mode=None # Enable Chromium's Guest mode.
778+
dark_mode=None # Enable Chromium's Dark mode.
779+
devtools=None # Open Chromium's DevTools when the browser opens.
780+
remote_debug=None # Enable Chrome's Debugger on "http://localhost:9222".
781+
enable_3d_apis=None # Enable WebGL and 3D APIs.
782+
swiftshader=None # Chrome: --use-gl=angle / --use-angle=swiftshader-webgl
783+
ad_block_on=None # Block some types of display ads from loading.
784+
host_resolver_rules=None # Set host-resolver-rules, comma-separated.
785+
block_images=None # Block images from loading during tests.
786+
do_not_track=None # Tell websites that you don't want to be tracked.
787+
chromium_arg=None # "ARG=N,ARG2" (Set Chromium args, ","-separated.)
788+
firefox_arg=None # "ARG=N,ARG2" (Set Firefox args, comma-separated.)
789+
firefox_pref=None # SET (Set Firefox PREFERENCE:VALUE set, ","-separated)
790+
user_data_dir=None # Set the Chrome user data directory to use.
791+
extension_zip=None # Load a Chrome Extension .zip|.crx, comma-separated.
792+
extension_dir=None # Load a Chrome Extension directory, comma-separated.
793+
disable_features=None # "F1,F2" (Disable Chrome features, ","-separated.)
794+
binary_location=None # Set path of the Chromium browser binary to use.
795+
driver_version=None # Set the chromedriver or uc_driver version to use.
796+
page_load_strategy=None # Set Chrome PLS to "normal", "eager", or "none".
797+
use_wire=None # Use selenium-wire's webdriver over selenium webdriver.
798+
external_pdf=None # Set Chrome "plugins.always_open_pdf_externally":True.
799+
window_position=None # Set the browser's starting window position: "X,Y"
800+
window_size=None # Set the browser's starting window size: "Width,Height"
801+
is_mobile=None # Use the mobile device emulator while running tests.
802+
mobile=None # Shortcut / Duplicate of "is_mobile".
803+
d_width=None # Set device width
804+
d_height=None # Set device height
805+
d_p_r=None # Set device pixel ratio
806+
position=None # Shortcut / Duplicate of "window_position".
807+
size=None # Shortcut / Duplicate of "window_size".
808+
uc=None # Shortcut / Duplicate of "undetectable".
809+
undetected=None # Shortcut / Duplicate of "undetectable".
810+
uc_cdp=None # Shortcut / Duplicate of "uc_cdp_events".
811+
uc_sub=None # Shortcut / Duplicate of "uc_subprocess".
812+
locale=None # Shortcut / Duplicate of "locale_code".
813+
log_cdp=None # Shortcut / Duplicate of "log_cdp_events".
814+
ad_block=None # Shortcut / Duplicate of "ad_block_on".
815+
server=None # Shortcut / Duplicate of "servername".
816+
guest=None # Shortcut / Duplicate of "guest_mode".
817+
wire=None # Shortcut / Duplicate of "use_wire".
818+
pls=None # Shortcut / Duplicate of "page_load_strategy".
819+
cft=None # Use "Chrome for Testing"
820+
chs=None # Use "Chrome-Headless-Shell"
821+
```
822+
823+
Example: [SeleniumBase/examples/raw_driver_manager.py](https://github.com/seleniumbase/SeleniumBase/blob/master/examples/raw_driver_manager.py)
824+
825+
--------
826+
827+
<a id="sb_cdp_chrome_options"></a>
828+
<h2><img src="https://seleniumbase.github.io/img/logo6.png" title="SeleniumBase" width="32" /> 04. <code>sb_cdp.Chrome()</code> method options</h2>
829+
830+
```python
831+
url: Optional[str] = None
832+
user_data_dir: Optional[PathLike] = None
833+
headless: Optional[bool] = False
834+
incognito: Optional[bool] = False
835+
guest: Optional[bool] = False
836+
browser_executable_path: Optional[PathLike] = None
837+
browser_args: Optional[List[str]] = None
838+
xvfb_metrics: Optional[List[str]] = None # "Width,Height" for Linux
839+
ad_block: Optional[bool] = False
840+
sandbox: Optional[bool] = True
841+
lang: Optional[str] = None # Set the Language Locale Code
842+
host: Optional[str] = None # Chrome remote-debugging-host
843+
port: Optional[int] = None # Chrome remote-debugging-port
844+
xvfb: Optional[int] = None # Use a special virtual display on Linux
845+
headed: Optional[bool] = None # Override default Xvfb mode on Linux
846+
expert: Optional[bool] = None # Open up closed Shadow-root elements
847+
agent: Optional[str] = None # Set the user-agent string
848+
proxy: Optional[str] = None # "host:port" or "user:pass@host:port"
849+
tzone: Optional[str] = None # Eg "America/New_York", "Asia/Kolkata"
850+
geoloc: Optional[list | tuple] = None # Eg (48.87645, 2.26340)
851+
extension_dir: Optional[str] = None # Chrome extension directory
852+
platform: Optional[str] = None # Set the Platform. Eg: "MacIntel"
853+
```
854+
855+
Example: [SeleniumBase/examples/cdp_mode/raw_geolocation.py](https://github.com/seleniumbase/SeleniumBase/blob/master/examples/cdp_mode/raw_geolocation.py)
856+
857+
--------
858+
859+
<a id="activate_cdp_mode_options"></a>
860+
<h2><img src="https://seleniumbase.github.io/img/logo6.png" title="SeleniumBase" width="32" /> 05. <code>activate_cdp_mode()</code> method options</h2>
861+
862+
```python
863+
url: Optional[str] = None # The URL to navigate to
864+
lang: Optional[str] = None # Set the Language Locale Code
865+
agent: Optional[str] = None # Set the user-agent string
866+
tzone: Optional[str] = None # Eg "America/New_York", "Asia/Kolkata"
867+
geoloc: Optional[list | tuple] = None # Eg (48.87645, 2.26340)
868+
platform: Optional[str] = None # Set the Platform. Eg: "MacIntel"
869+
```
870+
871+
Example: [SeleniumBase/examples/cdp_mode/raw_geolocation_sb.py](https://github.com/seleniumbase/SeleniumBase/blob/master/examples/cdp_mode/raw_geolocation_sb.py)
872+
873+
Note that if CDP Mode is already active, the options above can also be used when calling `sb.cdp.open()`. (The `url` arg is required in this case.)
874+
875+
--------
876+
607877
[<img src="https://seleniumbase.github.io/cdn/img/fancy_logo_14.png" title="SeleniumBase" width="290">](https://github.com/seleniumbase/SeleniumBase)

0 commit comments

Comments
 (0)