danp2 / au3webdriver Goto Github PK

View Code? Open in Web Editor NEW

102.0 11.0 21.0 1.53 MB

Web Driver UDF for AutoIt

License: MIT License

AutoIt 100.00%

autoit webdriver w3c udf

au3webdriver's Introduction

Welcome to `au3WebDriver`

Description

This au3WebDriver UDF (project) allows to interact with any browser that supports the W3C WebDriver specifications. Supporting multiple browsers via the same code base is now possible with just a few configuration settings.

Documentation

	Reference	Description
	W3C WebDriver	Official W3C WebDriver standard/specification.
📚	WebDriver Wiki	Further information about this UDF (project) like big picture, capabilities, troubleshooting and more.
📖	au3WebDriver.chm	Help file that comes with this UDF (project) download.
📙	Change Log	Record of all notable changes to the project

Features

Browser support

Chrome	Edge	Firefox	Opera

Functions

Core Functions

Name	Description
_WD_CreateSession	Request new session from web driver.
_WD_DeleteSession	Delete existing session.
_WD_Status	Get current web driver state.
_WD_GetSession	Get details on existing session.
_WD_Timeouts	Set or retrieve the session timeout parameters.
_WD_Navigate	Navigate to the designated URL.
_WD_Action	Perform various interactions with the web driver session.
_WD_Window	Perform interactions related to the current window.
_WD_FindElement	Find element(s) by designated strategy.
_WD_ElementAction	Perform action on designated element.
_WD_ExecuteScript	Execute Javascipt commands.
_WD_Alert	Respond to user prompt.
_WD_GetSource	Get page source.
_WD_Cookies	Gets, sets, or deletes the session's cookies.
_WD_Option	Sets and get options for the web driver UDF.
_WD_Startup	Launch the designated web driver console app.
_WD_Shutdown	Kill the web driver console app.

Helper Functions

Name	Description
_WD_Attach	Attach to existing browser tab.
_WD_CheckContext	Check if browser context is still valid.
_WD_ConsoleVisible	Control visibility of the webdriver console app.
_WD_DebugSwitch	Switch to new debug level or switch back to saved debug level.
_WD_DispatchEvent	Create and dispatch events.
_WD_DownloadFile	Download file and save to disk.
_WD_ElementActionEx	Perform advanced action on designated element.
_WD_ElementOptionSelect	Find and click on an option from a Select element.
_WD_ElementSelectAction	Perform action on designated Select element.
_WD_ElementStyle	Set/Get element style property.
_WD_FrameEnter	Enter the specified frame.
_WD_FrameLeave	Leave the current frame, to its parent.
_WD_FrameList	Retrieves a detailed list of the main document and all associated frames.
_WD_FrameListFindElement	Search the current document and return locations of matching elements.
_WD_GetBrowserPath	Retrieve path to browser executable from registry.
_WD_GetBrowserVersion	Get version number of specified browser.
_WD_GetContext	Retrieve the element ID of the current browsing context.
_WD_GetDevicePixelRatio	Returns an integer indicating the DevicePixelRatio.
_WD_GetElementById	Locate element by id.
_WD_GetElementByName	Locate element by name.
_WD_GetElementByRegEx	Find element by matching attributes values using Javascript regular expression.
_WD_GetElementFromPoint	Retrieves reference to element at specified point.
_WD_GetFrameCount	Returns the number of frames/iframes in the current document context.
_WD_GetFreePort	Locate and return an available TCP port within a defined range.
_WD_GetMouseElement	Retrieves reference to element below mouse pointer.
_WD_GetShadowRoot	Retrieves the shadow root of an element.
_WD_GetTable	Return all elements of a table.
_WD_GetWebDriverVersion	Get version number of specifed webdriver.
_WD_HighlightElements	Highlights the specified elements.
_WD_IsFullScreen	Return a boolean indicating if the session is in full screen mode.
_WD_IsLatestRelease	Compares local UDF version to latest release on Github.
_WD_IsWindowTop	Returns a boolean of the session being at the top level, or in a frame(s).
_WD_JsonActionKey	Formats keyboard "action" strings for use in _WD_Action
_WD_JsonActionPause	Formats pause "action" strings for use in _WD_Action
_WD_JsonActionPointer	Formats pointer "action" strings for use in _WD_Action
_WD_JsonCookie	Formats "cookie" JSON strings for use in _WD_Cookies.
_WD_LastHTTPResponse	Return the response of the last WinHTTP request.
_WD_LastHTTPResult	Return the result of the last WinHTTP request.
_WD_LinkClickByText	Simulate a mouse click on a link with text matching the provided string.
_WD_LoadWait	Wait for a browser page load to complete before returning.
_WD_NewTab	Create new tab in current browser session.
_WD_PrintToPDF	Print the current tab in paginated PDF format.
_WD_Screenshot	Takes a screenshot of the Window or Element.
_WD_SelectFiles	Select files for uploading to a website.
_WD_SetElementValue	Set value of designated element.
_WD_SetTimeouts	User friendly function to set webdriver session timeouts.
_WD_Storage	Provide access to the browser's localStorage and sessionStorage objects.
_WD_UpdateDriver	Replace web driver with newer version, if available.
_WD_WaitElement	Wait for an element in the current tab before returning.
_WD_WaitScript	Wait for a JavaScript snippet to return true.
_WD_jQuerify	Inject jQuery library into current session.

CDP Functions

Name	Description
_WD_CDPExecuteCommand	Execute CDP command.
_WD_CDPGetSettings	Retrieve CDP related settings from the browser.

Capabilities Functions

Name	Description
_WD_CapabilitiesStartup	Start new Capabilities build
_WD_CapabilitiesAdd	Add capablitities to JSON string
_WD_CapabilitiesGet	Get the JSON string
_WD_CapabilitiesDump	Dump to console
_WD_CapabilitiesDefine	Define a new capability by selecting a type and specifying a name

Getting started

Preconditions

Download and add the following mandatory Third-Party UDFs to your project folder (independent of the browser you want to automate).

Mandatory ✔
- Json UDF - Archive includes Json.au3 & BinaryCall.au3.
- WinHTTP UDF - Archive includes WinHttp.au3 & WinHttpConstants.au3.
Optional ⚠
- WinHttp_WebSocket UDF - Needed for websocket CDP functionality.

Download and install one of the following WebDrivers (depending on the browser type and version you want to automate).

Browser	Download	Implementation status
	Chrome	Status
	Edge	Status
	Firefox	Status ¹
	Opera	²

Limitation notice. ³

Installation

To automate your browser, follow the following steps.

Download at least the mandatory Third-Party UDFs.
Move the UDFs to your project folder or to a directory where AutoIt can find them.
- All wd_*.au3 files and the Third-Party UDFs *.au3 should be placed in the same directory.
- Otherwise you have to adjust the #include statements in the files.
Move your desired WebDriver of choice to the directory containing the wd_*.au3 files.

Usage

Run wd_demo.au3, choose your "Browser" from the dropdown and press the "Run Demo!" button that will perform the "DemoNavigation" demo to validate your installation.

Configuration

Useful information about possible configurations following soon.

Github Integration

To ensure your GitHub project always has the latest version of the UDF --

Open your prefered shell (cmd, powershell, bash, zsh)
Navigate to your GitHub Autoit repository
Run git submodule add https://github.com/Danp2/au3WebDriver
(OPTIONALLY) Run git mv au3WebDriver Includes\au3WebDriver to relocate the UDF into an Includes folder

Contributing

Just look at CONTRIBUTING, thank you!

License

Distributed under the MIT License. See LICENSE for more information.

Acknowledgements

Opportunity by GitHub
Badges by Shields
Thanks to the authors of the Third-Party UDFs
- Json UDF by @Ward and @Jos
- WinHTTP UDF by @trancexx/@dragana-r
- WinHttp_WebSocket UDF by @Danp2
Thanks to the maintainers
- Thanks to @Danp2 for the project idea, creation and maintenance
- Thanks to @mLipok for his wd_capabilities.au3
- Thanks to @Sven-Seyfert for the project logo
- Big thanks to all the hard-working contributors

To the top

Login Required ↩
Derived from ChromeDriver per project ReadMe ↩
Not all WebDriver functions have been fully implemented by each browser. Keep that in mind and check the "Implementation status" for your desired WebDriver of choice. ↩

au3webdriver's People

Contributors

Stargazers

Watchers

au3webdriver's Issues

How to recover from "Browsing context has been discarded"?

Originally reported here ==> https://www.autoitscript.com/forum/topic/192730-webdriver-udf-help-support/?do=findComment&comment=1415354

Was thought to be fixed in https://github.com/Danp2/WebDriver/releases/tag/0.1.0.17

_WDAlert issues

Expand error codes used to detect if alert is not found
Detect and handle non-present alert for various options

https://www.autoitscript.com/forum/topic/192730-webdriver-udf-help-support/?do=findComment&comment=1390827

_WD_Attach() - $_WD_ERROR_Success - question

As I said in title, in function: _WD_Attach() the returned @error $_WD_ERROR_Success will never happen because the Else part will be used.

Enhance _WDAlert to support the Get Alert Text and Send Alert Text options

wd_capabilities.au3 - TODO better error handling

as a project

_WD_ConsoleVisible(True) Hides Console

This is a little un-intuitive... when I pass True to _WD_ConsoleVisible, I would expect that the console would be visible, not hidden.

$sSelector part of the _WD_FindElement function must be enclosed in double quotes

https://www.autoitscript.com/forum/topic/191990-webdriver-udf-w3c-compliant-version-08042018/?do=findComment&comment=1399923

_WD_UpdateDriver: Maintain $bForce value when Null

This line --

https://github.com/Danp2/WebDriver/blob/3057014125c81c3f52e9a23451aa4b1efd2730e9/wd_helper.au3#L1290

changes the value of $bForce, essentially forcing an update even if the calling routine set $bForce = Null, indicating that the function should check for an update without actually performing the update.

This should be fixed so that the Null value is maintained / honored.

_WD_UpdateDriver: COM Errors

While I will admit some fault here, _WD_UpdateDriver doesn't handle any COM errors resulting from unzipping the downloaded driver. For example, try unzipping to a non-existent directory.

I see a couple ways to fix this:

include a COM error handler
check to see if the $sInstallDirectory exists and create it if not
Possibly: separate the lines with 2+ object level calls as this causes a fatal error (I think?) and check @error between

Happy to submit a pull request if you'd like, just let me know your preference :)

why DemoActions() uses _WD_Action() ?

After checking it looks like more adequte will be using _WD_ElementActionEx .
What you think about ?

_WD_WaitElement: Return element instead of static value

_WD_WaitElement can replace the redundant _WD_FindElement call if it returns the element instead of 1 on success.

Unused Variables/Strict Au3Check Settings

The variable $sErr is unused in the latest release (v0.3.0.1) in _WD_Window, _WD_FindElement, and _WD_ElementAction. When running with the strictest Au3Check parameters -d -w 1 -w 2 -w 3 -w 4 -w 5 -w 6 -w 7 -v3, a warning is generated

_WDExecuteScript doesn't support parameters

WD_Demo: Provide example on how to pass additional arguments to ChromeDriver

There is a difference in how additional arguments are passed to the web driver based on the browser being used.
The wd_demo provides an example of how to pass acceptInsecureCerts to the Firefox driver.

A similar example should be made available for the chrome function as well.

I will raise a PR for this soon.

_WD_ElementActionEx -- Too many closing brackets

https://www.autoitscript.com/forum/topic/205553-webdriver-udf-help-support-iii/?do=findComment&comment=1480674

_WD_HighlightElements() refactoring is needed

I will do this in future
currently this is just a reminder, I will propose new PR soon

SetTimeout unknown error: 'ms' must be a double

From here,

I tried the example code with chrome and received error when testing timeouts 'SetTimeout unknown error: 'ms' must be a double'.

Adding Examples

This is a placeholder for future discussions on adding examples to the UDF.

For starters --

According to specs, Example line is a simple Yes/No value.
Generated help file doesn't pick up the current non-compliant entries

_WD_CreateSession

Hi,

Chrome 83.

The SessionId is not stored in [Value] anymore

https://github.com/Danp2/WebDriver/blob/2f4d8cce692ac66b6c16a345c5466204a9a6deaf/wd_core.au3#L431

_WD_FindElement - cmd processing

In _WD_FindElement in case when $sStartNodeID = Default >> $sStartNodeID = ""

		$sBaseCmd = ($bShadowRoot) ? "/shadow/" : "/element/"
		$sBaseCmd &= $sStartNodeID
		.........
		$sCmd = '/element' & (($bMultiple) ? 's' : '')
		.........
		__WD_Post($_WD_BASE_URL & ":" & $_WD_PORT & "/session/" & $sSession & $sBaseCmd & $sCmd, ........

can occurs such scenario where $sBaseCmd & $sCmd will be /shadow//element or /element//element

Is this correct that // follow each other?
If this is an real issue and should be fixed, then I can propose fix for this.

[Regression] __WD_CloseDriver

__WD_CloseDriver doesn't work after rewrite if chromedriver path not default. Example:
_WD_Option("Driver", "ChromeDriver\chromedriver.exe")
After the script exit. Checking the task manager

I looked under the hood of the closing function to find out what the problem is, it seems that the new code does not return the process id if it is not the default path. Example:

_WD_SetElementValue - warning: $iMethod - not declared not used

Review timeout detection / handling for WinHTTP requests

Current detection appears incorrect. @error is 3 after call to _WinHttpSimpleSSLRequest, indicating 3 - could not receive response

Review / enhance functionality of _WD_Frame* functionality

Proper setting of @error flag
Standardization with other UDF functions

_WD_Startup -- Detect webdriver console exiting with error when launched

https://www.autoitscript.com/forum/topic/205553-webdriver-udf-help-support-iii/?do=findComment&comment=1493430

_WD_CapabilitiesAdd discussion

Per @TheDcoder on forum --

I would like to request adding the binary options to the vendor-specific options (similar to w3c), it can be used to set the path of the binary executable in Chrome Driver like so:

_WD_CapabilitiesAdd('binary', 'C:\Software\Chromium\bin\chrome.exe')

_WD_ElementSelectAction() refactoriong needed

If $iErr = $_WD_ERROR_Success And $sNodeName = 'select' Then

I will do this in a future.

_WD_IsLatestRelease fails under some operating systems

Windows Server 2016
Windows 7

_WD_FrameEnter fails with Chrome web driver

Originally reported here -- https://www.autoitscript.com/forum/topic/191990-webdriver-udf-w3c-compliant-version-07112018/?do=findComment&comment=1397460

$aDemoSuite new Col for Paramters

We should look for a better way to implement this that doesn't involve hardcoding function names. I think we could make this data driven by adding a column to $aDemoSuite. Also, it would make more sense to me to pass the browser name instead of the control ID. This would prevent the need from having code like $aBrowsers[_GUICtrlComboBox_GetCurSel($idBrowsers)][0] in multiple routines.

Originally posted by @Danp2 in #154 (comment)

_WD_ExecuteScript() $sJSONNode usage

In wd_helper.au3
all usage of _WD_ExecuteScript() should be reviewed to use: $vValueMode and proper @error returning

I will do this by proposing PR, as for now this Issue is only a reminder for me

Provide access to Firefox's CDP implementation

From the latest geckodriver release notes --

Introduced the new boolean capability moz:debuggerAddress that can be used
to opt-in to the experimental Chrome DevTools Protocol (CDP) implementation.
A string capability with the same name will be returned by NewSession,
which contains the host:port combination of the HTTP server that can be
used to query for websockets of available targets.

Details on moz:debuggerAddress can be found here.

Possibility of webdriver's background work

Hi, Danp2!
First of all, I'd like to appreciate your effort for this nice library.

I'm now developing a simple automation tool by using chrome webdriver, and everything is almost ok.
But the chrome always take the focus to itself while processing action, so I feel uncomfortable when I want to do some other works while running the script.
I found that the built-in functions of IE has no problem like this.
So my question is,
Is possible to make the chrome work in background like _IE functions?

I look forward to your reply.
Thank you.

DemoAlerts 'sendtext' issue on Chrome/MSEdge

using wd_demo.au3 in DemoAlerts() on Chrome and MSEdge this part

	; Set value of text field
	_WD_Alert($sSession, 'sendtext', 'new text')

dosen't work.
Any idea why ?

_WD_ElementActionEx() refactoring needed

$sAction
; Default "hover" action

I will do this in future

_WD_FrameLeave's Header

The syntax of _WD_FrameLeave says it doesn't accept any arguments currently, should be updated to this...

;#FUNCTION#===================================================================================================================
; Name ..........: _WD_FrameLeave
; Description ...: This will leave the current frame, to its parent, not necessarily the Top, for subsequent WebDriver operations.
; Syntax ........: _WD_FrameLeave($sSession)
; Parameters ....: $sSession            - Session ID from _WDCreateSession
; Return values .: Success      True
;                  Failure      - WD Response error message (E.g. "chrome not reachable")
; Author ........: Decibel
; Modified ......: 2018-04-27
; Remarks .......: ChromeDriver and GeckoDriver respond differently for a successful operation
; Related .......: 
; Link ..........: https://www.w3.org/TR/webdriver/#switch-to-parent-frame
; Example .......: No
;===============================================================================================================================

(took me waaay to long to realize that I could triple backticks to make a code block :D )

_WD_GetElementFromPoint doesn't support frames

https://www.autoitscript.com/forum/topic/192730-webdriver-udf-help-support/?page=25&tab=comments#comment-1414405

launching WD with Chrome extension

According to documentation ChromeDriver allows to load extencions in headless mode.
https://sites.google.com/a/chromium.org/chromedriver/extensions

ChromeOptions options = new ChromeOptions();
options.addArguments("load-extension=/path/to/extension");
ChromeDriver driver = new ChromeDriver(options);

How can I accomplish same result with AutoIT?

_WD_Option('Driver', 'chromedriver.exe')
_WD_Option('Port', 9515)
_WD_Option('DriverParams', '--log-path="' & @ScriptDir & '\chrome.log"')
$sDesiredCapabilities = '{"capabilities": {"alwaysMatch": {"goog:chromeOptions": {"w3c": true, "args":[ "--profile-directory=Default","load-extension=\extencsion"]}}}}'

snippet was my starting point, also _WD_Options was one of varaints, but no result.
What is correct method to tell chromedriver that I need to load an extencion?

__WD_CloseDriver

$sFile is unused after storing the result of the regular expression replacement in __WD_CloseDriver (v 0.3.0.6)

Clicking element, a question between 2 different ways

in wd_core.au3 we can use _WD_ElementAction to click with:

Case 'clear', 'click'
	$sResponse = __WD_Post($_WD_BASE_URL & ":" & $_WD_PORT & "/session/" & $sSession & "/element/" & $sElement & "/" & $sCommand, '{"id":"' & $sElement & '"}')
	$iErr = @error

in wd_helper.au3 we can use _WD_ElementActionEx with DOUBLECLICK :

which will be processed by:

				$sResponse = __WD_Post($sURL, $sOption)

The question is whether, in your experience, WebDriver handles clicks differently in these two cases?
For example, are there problems with one case and not with another?

Thus can we add to _WD_ElementActionEx not only DOUBLECLICK but also CLICK ?
Or should we treat that there is already CLICKANDHOLD ?
Does it make sense?

_WD_GetSession - Multiple Sessions

This doesn't appear to work with multiple sessions running. It returns the value of the response from the last session created.

Also, this causes $sSession and $sFuncName to go unused in the function :) Not sure why the commented out code, but I'm guessing this is a bit of a WIP? It claims to return a dictionary object, but returns a string as far as I can tell.

_WD_CheckContext - Return values

is this following description :

;                  Failure - Returns one of the following values:
;                  |$_WD_STATUS_Invalid (0) - Browser context is invalid
;                  |$_WD_ERROR_Exception

wrong or proper ?

$_WD_ERROR_Exception should not be returned as value but as @error

i faced This issue

https://ibb.co/60dHRJZ
(https://user-images.githubusercontent.com/94099046/141244890-4aa7aec7-6f8f-4772-967a-84d33c9dedac.png)

When i try use The compiled exe on windows 7 but it`s work on windows 10

and when run it (F5) as Script on windows 7 it`s work good .

i don't know the reason !

_WD_FindElement: Unable to find element from element

Multiple reports --

https://www.autoitscript.com/forum/topic/201106-webdriver-udf-help-support-ii/page/16/?tab=comments#comment-1453318

https://www.autoitscript.com/forum/topic/201106-webdriver-udf-help-support-ii/?do=findComment&comment=1460082

Enhance _WD_jQuerify to allow specification of alternate jQuery source file

https://www.autoitscript.com/forum/topic/192730-webdriver-udf-help-support/page/56/?tab=comments#comment-1442499