[WebDriver] Add info about importing tests

https://bugs.webkit.org/show_bug.cgi?id=220786

Reviewed by Carlos Garcia Campos.

Tools:

* Scripts/import-webdriver-tests: Replace optparse with argparse and
refer to the tests README.md
(Importer.import_tests):

WebDriverTests:

* README.md: Added.


Canonical link: https://commits.webkit.org/233246@main
git-svn-id: https://svn.webkit.org/repository/webkit/trunk@271739 268f45cc-cd09-0410-ab3c-d52691b4dbfc

Tools/ChangeLog

@@ -1,3 +1,14 @@
+2021-01-22  Lauro Moura  <[email protected]>
+
+        [WebDriver] Add info about importing tests
+        https://bugs.webkit.org/show_bug.cgi?id=220786
+
+        Reviewed by Carlos Garcia Campos.
+
+        * Scripts/import-webdriver-tests: Replace optparse with argparse and
+        refer to the tests README.md
+        (Importer.import_tests):
+
 2021-01-21  Aakash Jain  <[email protected]>
 
         [ews] Use github instead of svn.webkit.org to fetch contributors.json

Tools/Scripts/import-webdriver-tests

@@ -29,7 +29,7 @@
 
 import json
 import logging
-import optparse
+import argparse
 import os
 import sys
 
@@ -85,12 +85,13 @@ class Importer(object):
                 host.filesystem.copyfile(source_path, destination_path)
 
 
-option_parser = optparse.OptionParser(usage='usage: %prog [options]')
-option_parser.add_option('--w3c', action='store_true', dest='w3c',
+option_parser = argparse.ArgumentParser(description="Import webdriver tests from Selenium and W3C suites.",
+                                        epilog="Refer to WebDriverTests/README.md for more information.")
+option_parser.add_argument('--w3c', action='store_true', dest='w3c',
                          help='Import W3C tests')
-option_parser.add_option('--selenium', action='store_true', dest='selenium',
+option_parser.add_argument('--selenium', action='store_true', dest='selenium',
                          help='Import Selenium tests')
-options, _ = option_parser.parse_args()
+options = option_parser.parse_args()
 
 # Not giving any option means import all.
 if not options.w3c and not options.selenium:

WebDriverTests/ChangeLog

@@ -1,3 +1,12 @@
+2021-01-22  Lauro Moura  <[email protected]>
+
+        [WebDriver] Add info about importing tests
+        https://bugs.webkit.org/show_bug.cgi?id=220786
+
+        Reviewed by Carlos Garcia Campos.
+
+        * README.md: Added.
+
 2020-11-09  Lauro Moura  <[email protected]>
 
         [WebDriver] Gardening some WPE failures

WebDriverTests/README.md

@@ -0,0 +1,39 @@
+# WebDriver tests
+
+## Importing tests
+
+There is the `import-webdriver-tests` script to automate most of the process of
+checking out the repository and copying the files.
+
+It reads the `importer.json` of the selected suite (selenium or w3c), which
+contains the desired commit alongside the list of paths to skip/import.
+
+The cloned repository sits in `WebKitBuild/` for easier inspection. For example,
+to manually check the new commit to be imported.
+
+Once chosen the new commit, update `importer.json` with its hash and
+eventual path changes (e.g., new folders to be copied or skipped) and run the
+import script to update the desired suite:
+
+```
+./Tools/Scripts/import-webdriver-tests --selenium`
+./Tools/Scripts/import-webdriver-tests --w3c`
+```
+
+After running the script, if you're using git, you can check which files
+were added with `git status WebDriverTests/` to add them to the new commit.
+One current limitation of the script is its inability to check for deleted
+files from the source repository, so this step is still manual.
+
+Beware that when importing Selenium tests, some manual intervention might be
+needed to remove unsupported code related to Firefox, Chrome, etc. For example:
+
+* Package imports in `WebDriverTests/imported/selenium/py/selenium/webdriver/__init__.py`.
+* `RemoteConnection` objects in `WebDriverTests/imported/selenium/py/selenium/webdriver/remote/webdriver.py`.
+
+
+To test the imported suite, run it:
+
+```
+Tools/Scripts/run-webdriver-tests --verbose --wpe --release --display-server=xvfb
+```