diff --git a/contributing.md b/contributing.md index 48d7324a..a12236b1 100644 --- a/contributing.md +++ b/contributing.md @@ -49,14 +49,6 @@ We use the following for running functional tests. If you add or change a feature that reduces test coverage or causes a functional test to fail, then you also must submit a pull request to the [deformdemo](https://github.com/pylons/deformdemo) repository to go along with your functional test change to Deform. -:warning: Functional tests behave differently depending on whether you are looking at the browser window or using Xvfb. - -:information_source: Tests might not run correctly on Chrome due to various timing issues. -Some effort was put forth to fix this many years ago, but it was a never ending swamp. -[The situation might have improved recently](https://developers.google.com/web/updates/2017/04/headless-chrome). -We welcome pull requests to add this functionality. -To use google-chrome or Chromium, download the browser and respective webdriver, [chromiumdriver](https://chromedriver.chromium.org/downloads). - For functional tests, tox runs the shell script [run-selenium-tests.bash](https://github.com/Pylons/deform/blob/master/run-selenium-tests.bash), located at the root of the Deform repository. See its comments for a description. @@ -74,22 +66,6 @@ Run a single test. tox -e functional3 -- deformdemo.test:SequenceOfMaskedTextInputs.test_submit_one_filled -To run/edit/fix functional tests. -:note: This section has not worked for years, but could be improved for Firefox. - - source .tox/functional3/bin/activate - cd deformdemo # Checked out by tox functional3 - pserve demo.ini # Start web server - - # Run functional test suite using Chrome - WEBDRIVER="chrome" nosetests -x - - # Run functional test suite using Chrome, stop on pdb on exception - WEBDRIVER="chrome" nosetests -x --pdb - - # Run one functional test case using Chrome - WEBDRIVER="chrome" nosetests -x deformdemo.test:SequenceOfDateInputs - ### Preparing a functional testing environment @@ -98,9 +74,12 @@ We will assume that you put your projects in your user directory, although you c cd ~/projects/deform/ -Set an environment variable to add your local checkout of Deform to your PATH. +Set an environment variable to add your local checkout of Deform to your `PATH`. +Set a second environment variable `WEBDRIVER` to the executable file itself instead of the directory where it is extracted. +It must to be set before running tox or nosetest, otherwise Firefox or Chrome will not start and will return an error message of "driver not found". - export PATH=~/projects/deform/:$PATH + export PATH=~/projects/deform/firefox:$PATH + export WEBDRIVER= #### Firefox latest @@ -161,21 +140,22 @@ If you ever have problems building packages, you can always unlink it. apt-get install gettext apt-get install gettext-base -#### Xvfb -Xvfb is a X virtual framebuffer to run graphics in memory and on a server instead of forwarding the display to a desktop display using X11 forwarding and Xwindows. -macOS web browsers do not X11 and therefore do not need Xvfb. -However Linux systems require it. -Install Xvfb on Linux (Debian). - - apt-get install xvfb +#### Selenium -Set display and start Xvfb in the background. +Selenium is installed automatically by tox via `pip install -e .["testing"]`. - export DISPLAY=:99 - Xvfb :99 & +### Testing on Chrome or Chromium -#### Selenium +Tests might not run correctly on Chrome due to various timing issues. +Some effort was put forth to fix this many years ago, but it was a never ending swamp. +However, [the situation might have improved recently](https://developers.google.com/web/updates/2017/04/headless-chrome). -Selenium is installed automatically by tox via `pip install -e .["testing"]`. +If you accept the challenge, we welcome pull requests to this contributing guide, along with tests to support testing on Chrome. +The following are some clues to get you started. + +- To use google-chrome or Chromium, download the web browser and respective webdriver, [chromiumdriver](https://chromedriver.chromium.org/downloads). + These would be used instead of Firefox and geckodriver. +- Set the `WEBDRIVER` environment variable to chromiumdriver instead of geckodriver. +- Profit! Fun! World domination!