Skip to content

Commit ce2ff6a

Browse files
hhslepickahhslepicka
committed
DOC: Update documentation for WebBot and customizations.
1 parent 9756ead commit ce2ff6a

File tree

2 files changed

+151
-9
lines changed

2 files changed

+151
-9
lines changed

‎docs/bot.md‎

Lines changed: 7 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,13 @@
11
# Framework
22

3-
The `botcity.web` module contains specialized implementations aimed at Desktop automation
3+
The `botcity.web` module contains specialized implementations aimed at Web automation
44
such as `WebBot` which is described below.
55

6-
You are expected to implement the `action` method of the `DesktopBot` class in
6+
You are expected to implement the `action` method of the `WebBot` class in
77
your Bot class.
88

9-
Here is a very brief example of a bot which opens the BotCity website:
9+
Here is a very brief example of a bot which opens the BotCity website using Google Chrome and
10+
the ChromeDriver WebDriver to remote control the browser.
1011

1112
```python
1213
from botcity.web import WebBot
@@ -19,6 +20,9 @@ class Bot(WebBot):
1920

2021
# Opens the BotCity website.
2122
self.browse("https://botcity.dev/en")
23+
24+
# Wait for 10 seconds before closing everything
25+
self.sleep(10000)
2226

2327
# Stop the browser and clean up
2428
self.stop_browser()

‎docs/intro.md‎

Lines changed: 144 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,22 +1,160 @@
11
# Getting Started
22

3-
After you installed this package, the next step is to
4-
import the package into your code and start using the
3+
## Supported Browsers
4+
5+
This framework leverages the [WebDriver API](https://www.w3.org/TR/webdriver/) in order to communicate
6+
with browsers for Automation.
7+
8+
In doing so, it requires that the WebDriver for the chosen browser to be installed and available preferrably
9+
in your `PATH`. If you can't add the necessary WebDriver to your `PATH` you will be able to inform the `driver path`
10+
via code in your bot.
11+
12+
Here is a list of supported browsers along with links for you to download the proper WebDriver:
13+
14+
| Browser | WebDriver Download |
15+
|---------|--------------------------------------------------------------------------------|
16+
| Chrome | [ChromeDriver](https://sites.google.com/a/chromium.org/chromedriver/downloads) |
17+
| Firefox | [GeckoDriver](https://github.com/mozilla/geckodriver/releases) |
18+
19+
Please follow the instructions on the WebDriver website for installation and setup.
20+
21+
Once the desired WebDriver for the Web Browser to be used is installed we can proceed to the next steps.
22+
23+
## WebBot
24+
25+
After you installed this package, the next step is to import the package into your code and start using the
526
WebBot class to build your RPA pipeline.
627

728
```python
829
from botcity.web import *
930
```
1031

11-
## Template Project
32+
### Template Project
1233

13-
We created a template project using Cookiecutter to help
14-
you create new bots using BotCity's Python Framework.
34+
We created a template project using Cookiecutter to help you create new bots using BotCity's Python Framework.
1535

1636
Take a look into the [template project website](https://github.com/botcity-dev/bot-python-template) for more information
1737
on how to use it and get started.
1838

19-
## Next Steps
39+
### Customizing the Browser
40+
41+
To provide flexibility we have properties to allow you to configure which browser to use, the WebDriver
42+
location as well as the options used when launching the browser.
43+
44+
Over the next steps we will over the possible customizations in detail.
45+
46+
#### Selecting the Browser
47+
48+
The `WebBot` class by default comes configured to run with `Google Chrome`. You can select any other
49+
available browser by setting the `browser` property to one of the `Browser` *enum* available values.
50+
51+
Here is an example on how to change the default browser to be used:
52+
53+
```python
54+
from botcity.web import WebBot, Browser
55+
56+
57+
class Bot(WebBot):
58+
def action(self, execution):
59+
# Configure whether or not to run on headless mode
60+
self.headless = False
61+
62+
# Changes the Browser to Firefox
63+
self.browser = Browser.FIREFOX
64+
65+
# For Chrome
66+
# self.browser = Browser.CHROME
67+
68+
...
69+
```
70+
71+
From the snippet above the key takeaway is the `self.browser` piece in which we set it to one of the values
72+
from the `Browser` *enum* as mentioned before.
73+
74+
#### Defining the WebDriver Path
75+
76+
If your WebDriver for the selected browser is not available on the system `PATH` you can inform the location
77+
via the `driver_path` property.
78+
79+
Here is how that can be done:
80+
```python
81+
from botcity.web import WebBot, Browser
82+
83+
84+
class Bot(WebBot):
85+
def action(self, execution):
86+
# Configure whether or not to run on headless mode
87+
self.headless = False
88+
89+
# Inform the WebDriver path for Google Chrome's chromedriver
90+
self.driver_path = "/home/username/drivers/chromedriver"
91+
92+
...
93+
```
94+
95+
#### Customizing Browser Options
96+
97+
By default the browsers are launched with a set of curated options which we picked as essential.
98+
99+
Before getting into how to customize those details let's walk through some of the assumptions and
100+
details which are covered by the `default options`.
101+
102+
- **Headless Execution**: Depending on the `headless` property set on your Bot class we pick the
103+
proper configuration to launch the browser in the desired mode.
104+
105+
- **Downloads Folder Path**: By default we save all downloaded files on the Desktop folder.
106+
107+
- **User Profile**: By default we generate a temporary directory (which is later erased) to be used
108+
as the profile directory. This procedure ensure that every execution starts with a clean browser session
109+
and things such as cookies and stored passwords or certificates from one execution won't interfere with
110+
the others.
111+
112+
A handful of other options are also set and they can be inspected on the source code for each browser on the
113+
`botcity.web.browsers` module.
114+
115+
If you really need to customize the options you can do so via the `options` property. You can fetch
116+
the `default options` curated by BotCity and make your changes or start your options from scratch.
117+
118+
In the following snippet we will cover how to build on top of the existing options.
119+
120+
```python
121+
from botcity.web import WebBot, Browser
122+
123+
# For Chrome
124+
from botcity.web.browsers.chrome import default_options
125+
# For Firefox
126+
#from botcity.web.browsers.firefox import default_options
127+
128+
class Bot(WebBot):
129+
def action(self, execution):
130+
# Configure whether or not to run on headless mode
131+
self.headless = False
132+
133+
# Fetch the default options for my preferred browser
134+
# Pass in the headless, download_folder_path and user_data_dir
135+
# to be used when building the default_options
136+
def_options = default_options(
137+
headless=self.headless,
138+
download_folder_path=self.download_folder_path,
139+
user_data_dir=None # Informing None here will generate a temporary directory
140+
)
141+
142+
# Add your customized argument
143+
def_options.add_argument("<My Special Argument>")
144+
145+
# Update the options to use the customized Options.
146+
self.options = def_options
147+
148+
...
149+
```
150+
151+
Every supported browser will have an exclusive module with curated default options accessible via the module's
152+
`default_options` function.
153+
154+
This function takes in arguments to define the mode of execution (headless or not), default download folder path
155+
and user data/profile directory.
156+
157+
### Next Steps
20158

21159
Check our examples and experiment with the API.
22160
Let us know where it can be improved.

0 commit comments

Comments
 (0)