From 245c77a6ebeaa92d08384900905298598a9fbfbc Mon Sep 17 00:00:00 2001
From: Julien Boyer <julien@larevolution.re>
Date: Tue, 1 Aug 2023 20:19:49 +0200
Subject: [PATCH] Full setup for system tests

Signed-off-by: Julien Boyer <julien@larevolution.re>
Signed-off-by: sitarane <julien@larevolution.re>
---
 .../rails/README.md                           | 72 +++++++++++++++++++
 1 file changed, 72 insertions(+)

diff --git a/official-documentation-samples/rails/README.md b/official-documentation-samples/rails/README.md
index b9bda82..b381edc 100644
--- a/official-documentation-samples/rails/README.md
+++ b/official-documentation-samples/rails/README.md
@@ -394,6 +394,78 @@ these tests won't work yet, as we need to point Rails to the Chrome browser incl
 
 If you don't need system tests, ignore this and comment out the "chrome-server" service.
 
+### Set up the browser for system tests
+
+#### Point Capybara to the browser
+
+Rails expects the browser to be local. We need to point it to the chrome-server.
+
+Add the options to the driver definition in test/application_system_test_case.rb
+
+```ruby
+driven_by :selenium, using: :chrome, screen_size: [1400, 1400], options: {
+    browser: :remote,
+    url: "http://chrome-server:4444/wd/hub"
+  }
+```
+
+#### Point the browser to your app
+
+In test/test_helper.rb, add:
+
+```ruby
+Capybara.server_host = "0.0.0.0"
+Capybara.app_host = "http://#{ENV.fetch("HOSTNAME")}:#{Capybara.server_port}"
+```
+It should be at the base of the file, outside of the TestCase class definition.
+
+Now you can run your system tests:
+
+```bash
+docker compose run test rails test
+```
+
+#### Watch the system tests run
+
+The chrome-server definition has an open port on the host:
+
+```yaml
+chrome-server:
+  image: selenium/standalone-chrome
+  ports:
+    - "7900:7900"
+```
+This is so that you can watch them execute in the browser.
+
+Before running your tests, start the chrome-server:
+
+```bash
+docker compose run chrome-server
+```
+Once it's up, visit localhost:7900 on your browser.
+
+Click on "connect", enter the secret password (it's "secret"), and you'll see
+a GUI workspace.
+
+Now, from another terminal, launch your tests:
+
+```bash
+docker compose run test rails test:system
+```
+And watch a browser window (inside your browser window) go through all the steps.
+
+Better with popcorn.
+
+When you get tired of watching, you can remove the open ports on the "chrome-server" service
+in the docker-compose file, and change the Selenium driver to :headless_chrome. It'll be a
+little faster:
+
+In test/application_system_test_case.rb:
+
+```ruby
+driven_by :selenium, using: :headless_chrome # ....
+```
+
 ## More Compose documentation
 
 * [Docker Compose overview](https://docs.docker.com/compose/)