Merge branch 'robotframework:master' into master

Author: yuriverweij

.github/workflows/CI.yml

@@ -10,13 +10,14 @@ jobs:
     strategy:
       matrix:
         python-version: [3.8, 3.11]  # 3.12, pypy-3.9
-        rf-version: [5.0.1, 6.1.1, 7.0b1]
-        selenium-version: [4.14.0, 4.15.2, 4.16.0]
+        rf-version: [5.0.1, 6.1.1, 7.0]
+        selenium-version: [4.14.0, 4.15.2, 4.16.0, 4.17.2, 4.18.1, 4.19.0]
+        browser: [firefox, chrome, headlesschrome]  #edge
 
     steps:
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v4
     - name: Set up Python ${{ matrix.python-version }} with Robot Framework ${{ matrix.rf-version }}
-      uses: actions/setup-python@v4
+      uses: actions/setup-python@v5
       with:
         python-version: ${{ matrix.python-version }}
     - name: Setup Chrome
@@ -27,6 +28,14 @@ jobs:
     - run: |
         echo Installed chromium version: ${{ steps.setup-chrome.outputs.chrome-version }}
         ${{ steps.setup-chrome.outputs.chrome-path }} --version
+    - name: Setup firefox
+      id: setup-firefox
+      uses: browser-actions/setup-firefox@v1
+      with:
+        firefox-version: latest
+    - run: |
+        echo Installed firefox versions: ${{ steps.setup-firefox.outputs.firefox-version }}
+        ${{ steps.setup-firefox.outputs.firefox-path }} --version
     - name: Start xvfb
       run: |
         export DISPLAY=:99.0
@@ -62,25 +71,14 @@ jobs:
 
     # Temporarily ignoring pypy execution
     - name: Run tests with headless Chrome and with PyPy
-      if: matrix.python-version == 'pypy-3.9'
+      if: startsWith( matrix.python-version, 'pypy') == true
       run: |
         xvfb-run --auto-servernum python atest/run.py --nounit --zip headlesschrome
 
-    - name: Run tests with normal Chrome if CPython
-      if: matrix.python-version != 'pypy-3.9'
-      run: |
-        xvfb-run --auto-servernum python atest/run.py --zip chrome
-
-    # Recognize for the moment this will NOT run as we aren't using Python 3.9
-    - name: Run tests with headless Firefox with Python 3.9 and RF 4.1.3
-      if: matrix.python-version == '3.9' && matrix.rf-version == '4.1.3'
-      run: |
-        xvfb-run --auto-servernum python atest/run.py --zip headlessfirefox
-
-    - name: Run tests with normal Firefox with Python 3.9 and RF != 4.1.3
-      if: matrix.python-version == '3.9' && matrix.rf-version != '4.1.3'
+    - name: Run tests with ${{ matrix.browser }} if CPython
+      if: startsWith( matrix.python-version, 'pypy') == false
       run: |
-        xvfb-run --auto-servernum python atest/run.py --zip firefox
+        xvfb-run --auto-servernum python atest/run.py --zip ${{ matrix.browser }}
 
     # - name: Run tests with Selenium Grid
     #   if: matrix.python-version == '3.11' && matrix.rf-version == '3.2.2' && matrix.python-version != 'pypy-3.9'
@@ -90,7 +88,7 @@ jobs:
     #     xvfb-run --auto-servernum python atest/run.py --zip headlesschrome  --grid True
 
     - uses: actions/upload-artifact@v1
-      if: success() || failure()
+      if: failure()
       with:
         name: SeleniumLibrary Test results
         path: atest/zip_results

BUILD.rst

@@ -64,7 +64,8 @@ Testing
 -------
 
 Make sure that adequate tests are executed before releases are created.
-See `<test/README.rst>`_ for details.
+For more information about unit tests see `<utest/README.rst>`_ or for
+acceptance tests see `<atest/README.rst>`_.
 
 Preparation
 -----------

CONTRIBUTING.rst

@@ -3,21 +3,22 @@ Contribution guidelines
 
 These guidelines instruct how to submit issues and contribute code to
 the `SeleniumLibrary project`_. Other great ways to contribute include
-answering questions and participating discussion on `robotframework-users`_
-mailing list and other forums as well as spreading the word about the
-framework one way or the other.
+answering questions and participating in discussions within the
+#seleniumlibrary channel on the community `Robot Framework Slack`_, the
+`Robot Framework Forum`_ and other channels as well as spreading the word
+about the framework one way or the other.
 
 Submitting issues
 =================
 
 Bugs and enhancements are tracked in the `issue tracker`_.
 If you are unsure if something is a bug or is a feature worth
-implementing, you can first ask on `robotframework-users`_ list. This and
+implementing, you can first ask within the `Robot Framework Slack`_. This and
 other similar forums, not the issue tracker, are also places where to ask
 general questions.
 
-Before submitting a new issue, it is always a good idea to check is the
-same bug or enhancement already reported. If it is, please add your
+Before submitting a new issue, it is always a good idea to check if the
+same bug or enhancement is already reported. If it is, please add your
 comments to the existing issue instead of creating a new one.
 
 Reporting bugs
@@ -43,9 +44,11 @@ Enhancement requests
 
 Describe the new feature and use cases for it in as much detail as
 possible in an issue. Especially with larger enhancements, be prepared to
-contribute the code in form of a pull request as explained below or to
+contribute the code in the form of a pull request as explained below or to
 pay someone for the work. Consider also would it be better to implement this
-functionality as a separate library outside the SeleniumLibrary.
+functionality as a separate library outside the SeleniumLibrary. One option
+here is to extend SeleniumLibrary using the public API or plug-in api. Please
+see `extending documentation`_ for more details.
 
 Code contributions
 ==================
@@ -88,17 +91,25 @@ We do, however, recommend to create dedicated branches for pull requests
 instead of creating them based on the master branch. This is especially
 important if you plan to work on multiple pull requests at the same time.
 
-This project requires that pull request contains linear history of commits and
-we do not allow that pull request contains merge commits or other noise. This helps
-the review process and makes the maintenance easier for the project administrators.
-Generally it is recommended to do `git pull --rebase`  instead of the `git pull --merge`
-when there is need pull changes from upstream.
+This project asks that prior to making an enhancement pull request that you
+discuss the enhancement with the team. We wish to avoid having you spend effort on an
+ehancement that won't match with the project. We require that a pull request contains
+linear history of commits and we do not allow that pull request contains merge commits
+or other noise. This helps the review process and makes the maintenance easier for the
+project administrators. Generally it is recommended to do `git pull --rebase`  instead
+of the `git pull --merge` when there is need pull changes from upstream.
 
 Coding conventions
 ------------------
 
+The SeleniumLibrary team is currently reviewing, revising, and updating
+the coding conventions during Q1 2024. Knowing these coding conventions
+are seen as a good practice, we are leaving these here as recommendations
+in the mean time but are not forcing this as a requirement for accepting
+pull requests.
+
 SeleniumLibrary uses the general Python code conventions defined in
-`PEP-8`_. In addition to that, we try to write `idiomatic Python`_
+`PEP-8`_. In addition to that, we try to write `idiomatic Python`_ or `"Pythonic" code`_
 and follow the `SOLID principles`_. with all new code. An important guideline
 is that the code should be clear enough that comments are generally not needed.
 
@@ -145,7 +156,7 @@ individual keywords.
 
 -  All new enhancements or changes should have a note telling when the
    change was introduced. Often adding something like
-   ``New in SeleniumLibray 1.8.`` is enough.
+   ``New in SeleniumLibrary 1.8.`` is enough.
 
 Keyword documentation can be easily created using `invoke`_ task::
 
@@ -159,34 +170,38 @@ Tests
 When submitting a pull request with a new feature or a fix, you should
 always include tests for your changes. These tests prove that your
 changes work, help prevent bugs in the future, and help document what
-your changes do. Depending an the change, you may need
-``acceptance tests``\ *, ``unit tests``* or both.
+your changes do. Depending an the change, you may need ``acceptance tests``,
+``unit tests`` or both.
 
 Make sure to run all of the tests before submitting a pull request to be
 sure that your changes do not break anything. If you can, test in
 multiple browsers and versions (Firefox, Chrome, IE, Edge etc). Pull requests
-are also automatically tested on `Travis CI`_.
+are also automatically tested on `GitHub Actions`_.
 
 Acceptance tests
 ~~~~~~~~~~~~~~~~
 
 Most of SeleniumLibrary's testing is done using acceptance tests that
 naturally use Robot Framework itself for testing. Every new
 functionality or fix should generally get one or more acceptance tests.
+For more details on acceptance tests and how to run the acceptance tests,
+see `atest/README.rst`_.
 
 Unit tests
 ~~~~~~~~~~
 
 Unit tests are great for testing internal logic and should be added when
-appropriate. For more details see `Unit and acceptance
-tests <https://github.com/robotframework/SeleniumLibrary/blob/master/BUILD.rst#unit-and-acceptance-tests%3E>`__.
+appropriate. For more details on unit tests and running them, see
+`utest/README.rst`_.
 
 Continuous integration
 ----------------------
 
-SeleniumLibrary's continuous integration (CI) servers are visible through
-`Travis CI`_. For more details about how to run test and how `Travis CI`_
-integration is implemented can be found from the `test/README.rst`_.
+SeleniumLibrary uses GitHub Actions as it's continuous integration (CI) server.
+
+.. ToDo: re-add when explanation of GitHUb Actions is written
+   More details about how `GitHub Actions`_ integration is implemented can be
+   found within `<.github/CI/README.rst>.
 
 Finalizing pull requests
 ------------------------
@@ -198,7 +213,7 @@ Acknowledgments
 ~~~~~~~~~~~~~~~
 
 If you have done any non-trivial change and would like to be credited,
-remind us to add `acknowledge` tag to the issue. This way we will add
+remind us to add ``acknowledge`` tag to the issue. This way we will add
 your name to the release notes, when next release is made.
 
 Resolving conflicts
@@ -209,22 +224,26 @@ the same code as your changes. In that case you should
 `sync your fork`_ and `resolve conflicts`_ to allow for an easy merge.
 
 .. _SeleniumLibrary project: https://github.com/robotframework/SeleniumLibrary
-.. _robotframework-users: http://groups.google.com/group/robotframework-users
+.. _Robot Framework Slack: https://rf-invite.herokuapp.com/
+.. _Robot Framework Forum: https://forum.robotframework.org/c/libraries/lib-seleniumlibrary/11
 .. _issue tracker: https://github.com/robotframework/SeleniumLibrary/issues
 .. _(SSCCE): http://sscce.org
+.. _extending documentation: https://github.com/robotframework/SeleniumLibrary/blob/master/docs/extending/extending.rst
 .. _GitHub account: https://github.com/
 .. _Git: https://git-scm.com
 .. _set up Git: https://help.github.com/articles/set-up-git/
 .. _fork a repository: https://help.github.com/articles/fork-a-repo/
 .. _use pull requests: https://help.github.com/articles/using-pull-requests
 .. _PEP-8: https://www.python.org/dev/peps/pep-0008/
-.. _idiomatic Python: http://python.net/~goodger/projects/pycon/2007/idiomatic/handout.html
+.. _idiomatic Python: https://en.wikibooks.org/wiki/Python_Programming/Idioms
+.. _"Pythonic" code: https://docs.python-guide.org/writing/style/
 .. _SOLID principles: https://en.wikipedia.org/wiki/SOLID_(object-oriented_design)
 .. _PEP-257: https://www.python.org/dev/peps/pep-0257/
 .. _invoke: http://www.pyinvoke.org/
-.. _Travis CI: https://travis-ci.org/robotframework/SeleniumLibrary
-.. _test/README.rst`: https://github.com/robotframework/SeleniumLibrary/blob/master/test/README.rst
+.. _GitHub Actions: https://github.com/robotframework/SeleniumLibrary/actions
+.. _atest/README.rst: https://github.com/robotframework/SeleniumLibrary/tree/master/atest/README.rst
+.. _utest/README.rst: https://github.com/robotframework/SeleniumLibrary/blob/master/utest/README.rst
 .. _sync your fork: https://help.github.com/articles/syncing-a-fork/
 .. _resolve conflicts: https://help.github.com/articles/resolving-a-merge-conflict-from-the-command-line
 .. _Black: https://github.com/psf/black
-.. _flake8: https://gitlab.com/pycqa/flake8
+.. _flake8: https://github.com/PyCQA/flake8

atest/acceptance/expected_conditions.robot.PROTOTYPE

@@ -0,0 +1,34 @@
+*** Test Cases ***
+# Wait Until Element State Is (Not)
+# Get Element State
+# Element States Should (Not) Be
+
+Check waiting for condition that takes a element
+   Fail
+
+Check waiting for condition that takes a title
+   Fail
+
+Check waiting for condition that takes a url
+   Fail
+   Wait Until    url contains   google
+   # verify took 2 seconds
+
+Check waiting for condition that takes locator and string
+   Wait Until Element State Is     ${condition}    ${locator}   ${string}
+   Wait Until Element State Is     ${condition}    ${element}
+   Wait Until Condition Is         ${condition}    ${target}
+   Wait Until Condition Is         ${condition}    ${whatelse you need for this condition}
+
+
+   Wait Until State Is         number_of_windows_to_be
+   Wait Until Expected Condition Is         number_of_windows_to_be
+   Wait Until Condition Is     number of windows to be   5
+   Wait Until Condition Is     text to be present in element attribute    //some/xpath/to/an/element  href  http://hello
+
+   Wait Until Condition Is     number of windows to be   5    text to be present in element attribute    //some/xpath/to/an/element  href  http://hello
+
+   Wait Until    number of windows to be   5
+   Wait Until    text to be present in element attribute    //some/xpath/to/an/element  href  http://hello   
+   Get Condition
+   Is       number of windows to be   5

atest/acceptance/keywords/choose_file.robot

@@ -45,11 +45,11 @@ Choose File With Grid From Library Using SL choose_file method
 
 Input Text Should Work Same Way When Not Using Grid
     [Documentation]
-    ...    LOG 1:6 DEBUG GLOB:    POST*/session/*/clear {*
-    ...    LOG 1:9 DEBUG          Finished Request
-    ...    LOG 1:10 DEBUG GLOB:    POST*/session/*/value*"text": "*
-    ...    LOG 1:13 DEBUG         Finished Request
-    ...    LOG 1:14 DEBUG         NONE
+    ...    LOG 1:6 DEBUG GLOB:     POST*/session/*/clear {*
+    ...    LOG 1:9 DEBUG           Finished Request
+    ...    LOG 1:10 DEBUG REGEXP:  POST.*/session/.*/value.*['\\\"]text['\\\"]: ['\\\"].*
+    ...    LOG 1:13 DEBUG          Finished Request
+    ...    LOG 1:14 DEBUG          NONE
     [Tags]    NoGrid
     [Setup]    Touch    ${CURDIR}${/}temp.txt
     Input Text    file_to_upload    ${CURDIR}${/}temp.txt

atest/acceptance/keywords/click_element.robot

@@ -40,7 +40,7 @@ Click Element Action Chain
     [Tags]    NoGrid
     [Documentation]
     ...    LOB 1:1 INFO        Clicking 'singleClickButton' using an action chain.
-    ...    LOG 1:6 DEBUG GLOB: *actions {"actions": [{*
+    ...    LOG 1:6 DEBUG REGEXP: .*actions {['\\\"]actions['\\\"]: \\\[\\\{.*
     Click Element    singleClickButton      action_chain=True
     Element Text Should Be    output    single clicked
 

atest/acceptance/keywords/cookies.robot

@@ -49,8 +49,9 @@ Add Cookie When Expiry Is Human Readable Data&Time
 Delete Cookie
     [Tags]    Known Issue Safari
     Delete Cookie    test
-    ${cookies} =    Get Cookies
-    Should Be Equal    ${cookies}    far_future=timemachine; another=value
+    ${cookies} =    Get Cookies  as_dict=True
+    ${expected_cookies}  Create Dictionary  far_future=timemachine  another=value
+    Dictionaries Should Be Equal    ${cookies}    ${expected_cookies}
 
 Non-existent Cookie
     Run Keyword And Expect Error

atest/acceptance/keywords/expected_conditions.robot

@@ -0,0 +1,52 @@
+*** Settings ***
+Test Setup        Go To Page "javascript/expected_conditions.html"
+Resource          ../resource.robot
+
+*** Test Cases ***
+Wait For Expected Conditions One Argument
+    Title Should Be    Original
+    Click Element    link=delayed change title
+    Wait For Expected Condition    title_is    Delayed
+    Title Should Be    Delayed
+
+Wait For Expected Condition Times out within set timeout
+    [Documentation]  FAIL REGEXP: TimeoutException: Message: Expected Condition not met within set timeout of 0.3*
+    Title Should Be    Original
+    Click Element    link=delayed change title
+    Wait For Expected Condition   title_is  Delayed  timeout=0.3
+
+Wait For Expected Conditions using WebElement as locator
+    Click Button    Change the button state
+    ${dynamic_btn}=  Get WebElement  id:enabledDisabledBtn
+    Wait For Expected Condition  element_to_be_clickable  ${dynamic_btn}
+
+Wait For Expected Conditions Where Condition Written With Spaces
+    Title Should Be    Original
+    Click Element    link=delayed change title
+    Wait For Expected Condition    title is    Delayed
+    Title Should Be    Delayed
+
+Wait For Expected Conditions Where Condition Is Variable
+    ${condition}=  Set Variable  title is
+    Title Should Be    Original
+    Click Element    link=delayed change title
+    Wait For Expected Condition    ${condition}    Delayed
+    Title Should Be    Delayed
+
+Wait For Expected Conditions Where Condition Is Strange Case
+    Click Button    Change the button state
+    ${dynamic_btn}=  Get WebElement  id:enabledDisabledBtn
+    Wait For Expected Condition  EleMENT tO BE cLiCkAbLe  ${dynamic_btn}
+
+Wait For Non Existing Expected Conditions
+    Click Button    Change the button state
+    ${dynamic_btn}=  Get WebElement  id:enabledDisabledBtn
+    Run Keyword And Expect Error   this_is_not_an_expected_con_dition is an unknown expected condition
+    ...  Wait For Expected Condition  this_is not an expected con dition  ${dynamic_btn}
+
+Wait For Expected Conditions When Condition Includes Locator
+    Title Should Be    Original
+    ${byElem}=  Evaluate  ("id","added_btn")
+    Click Element    link:delayed add element
+    Wait For Expected Condition    Presence Of Element Located    ${byElem}
+    Click Element    id:added_btn