#432 improved/extended special readme about tests

CONTRIBUTING.md

@@ -16,17 +16,20 @@ By participating, you agree to abide by its terms.
 
 ## Contributing code
 
-If you'd like to contribute code to NiceGUI, we're always looking for bug fixes, performance improvements, and new features.
+We are excited that you want to contribute code to NiceGUI.
+We're always looking for bug fixes, performance improvements, and new features.
 
 ## Setup
 
-To set up a local development environment for NiceGUI, you'll need to have Python 3 and pip installed. You can then use the following command to install NiceGUI in editable mode:
+To set up a local development environment for NiceGUI, you'll need to have Python 3 and pip installed.
+You can then use the following command to install NiceGUI in editable mode:
 
 ```bash
 python3 -m pip install -e .
 ```
 
-This will install the package and its dependencies, and link it to your local development environment so that changes you make to the code will be immediately reflected.
+This will install the package and its dependencies,
+and link it to your local development environment so that changes you make to the code will be immediately reflected.
 Thereby enabling you to use your local version of NiceGUI in other projects.
 
 ### Code formatting
@@ -45,17 +48,16 @@ Then the formatting rules are applied whenever you save a file.
 ## Running tests
 
 Our tests are build with pytest and require python-selenium with Chrome driver.
+See [tests/README.md](https://github.com/zauberzeug/nicegui/blob/main/tests/README.md) for detailed installation instructions and more infos about the test infrastructure and tricks for daily usage.
 
-To run the tests, use the following command:
+Before submitting a pull request, please make sure that all tests are passing.
+To run them all, use the following command in the root directory of NiceGUI:
 
 ```bash
 pytest
 
 ```
 
-This will run all of the tests in the tests directory.
-Before submitting a pull request, please make sure that all tests are passing.
-
 ## Pull requests
 
 To get started, fork the repository on GitHub, make your changes, and open a pull request (PR) with a detailed description of the changes you've made.

tests/README.md

@@ -1,7 +1,16 @@
 # Automated Tests for NiceGUI
 
+## Motivation
+
+Testing a user interface is hard work.
+But to ensure NiceGUI is working as expected it is of utmost importance.
+Even if automated testing needs a lot of infrastructure and results in long execution times, we believe that it's worth the effort when compared to manual testing.
+
 ## Setup
 
+Please be aware that the below commands installs the latest version of the ChromeDriver binary, which is compatible with the version of Google Chrome installed on your system.
+If you have a different version of Chrome installed, you may need to install a different version of ChromeDriver or update your Chrome installation to be compatible with the installed ChromeDriver version.
+
 ### Mac
 
 ```bash
@@ -10,7 +19,53 @@ brew install cask chromedriver
 python3 -m pip install -r tests/requirements.txt
 ```
 
+Note: The above instructions assume that you have already installed Homebrew (a package manager for macOS) on your system.
+If you haven't, you can follow the instructions on https://brew.sh/ to install it.
+
+### Windows
+
+```powershell
+cd nicegui # enter the project root dir
+choco install chromedriver
+python3 -m pip install -r tests/requirements.txt
+```
+
+Note: The above instructions assume that you have already installed Chocolatey (a package manager for Windows) on your system. If you haven't, you can follow the instructions on https://chocolatey.org/install to install it.
+
+```bash
+cd nicegui # enter the project root dir
+sudo apt-get update
+sudo apt-get install chromium-chromedriver
+python3 -m pip install -r tests/requirements.txt
+```
+
+Note: The above instructions assume that you are using a Debian-based Linux distribution. If you are using a different distribution, the package manager and package names may differ. Please refer to the documentation for your distribution for more information.
+
 ## Usage
 
-Use selenium-fixture to control and query the website.
-See https://selenium-python.readthedocs.io/getting-started.html for documentation of the available method calls to the webdriver.
+Because selenium queries are quite cumbersome and lengthily, we introduced a `Screen` class.
+This provides a high-level interface to work with the currently displayed state of the web browser.
+The workflow is as follows:
+
+1. get the screen fixture by providing `screen: Screen` as an argument to the function
+2. write your NiceGUI code inside the function
+3. use `screen.open(...)` with the appropriate url path to start querying the website
+4. for example use `screen.should_contain(...)` with some text as parameter to ensure that the text is shown
+
+Here is a very simple example:
+
+```py
+from nicegui import ui
+from .screen import Screen
+
+def test_hello_world(screen: Screen):
+    ui.label('Hello, world')
+
+    screen.open('/')
+    screen.should_contain('Hello, world')
+```
+
+Have a look at the existing tests for more examples.
+Internally we use selenium-fixture (see `conftest.py`).
+To access the webdriver directly you can use the `screen.selenium` property.
+Have a look at https://selenium-python.readthedocs.io/getting-started.html for documentation of the available method calls to the webdriver.