diff options
Diffstat (limited to 'doc/development/testing_guide/end_to_end')
| -rw-r--r-- | doc/development/testing_guide/end_to_end/beginners_guide.md | 5 | ||||
| -rw-r--r-- | doc/development/testing_guide/end_to_end/capybara_to_chemlab_migration_guide.md | 148 | ||||
| -rw-r--r-- | doc/development/testing_guide/end_to_end/img/gl-capybara_V13_12.png | bin | 0 -> 19201 bytes | |||
| -rw-r--r-- | doc/development/testing_guide/end_to_end/img/gl-chemlab_V13_12.png | bin | 0 -> 17753 bytes | |||
| -rw-r--r-- | doc/development/testing_guide/end_to_end/page_objects.md | 2 | ||||
| -rw-r--r-- | doc/development/testing_guide/end_to_end/running_tests_that_require_special_setup.md | 8 |
6 files changed, 156 insertions, 7 deletions
diff --git a/doc/development/testing_guide/end_to_end/beginners_guide.md b/doc/development/testing_guide/end_to_end/beginners_guide.md index 29f6c93d65a..7cde2cad300 100644 --- a/doc/development/testing_guide/end_to_end/beginners_guide.md +++ b/doc/development/testing_guide/end_to_end/beginners_guide.md @@ -210,7 +210,7 @@ end Behind the scenes, `be_signed_in` is a [predicate matcher](https://relishapp.com/rspec/rspec-expectations/v/3-8/docs/built-in-matchers/predicate-matchers) -that [implements checking the user avatar](https://gitlab.com/gitlab-org/gitlab/-/blob/master/qa/qa/page/main/menu.rb#L74). +that [implements checking the user avatar](https://gitlab.com/gitlab-org/gitlab/-/blob/master/qa/qa/page/main/menu.rb#L92). ## De-duplicate your code @@ -339,11 +339,12 @@ Before running the spec, make sure that: - No additional [RSpec metadata tags](rspec_metadata_tests.md) have been applied. - Your working directory is `qa/` within your GDK GitLab installation. - Your GitLab instance-level settings are default. If you changed the default settings, some tests might have unexpected results. +- Because the GDK requires a password change on first login, you must include the GDK password for `root` user To run the spec, run the following command: ```ruby -bundle exec bin/qa Test::Instance::All http://localhost:3000 -- <test_file> +GITLAB_PASSWORD=<GDK root password> bundle exec bin/qa Test::Instance::All http://localhost:3000 -- <test_file> ``` Where `<test_file>` is: diff --git a/doc/development/testing_guide/end_to_end/capybara_to_chemlab_migration_guide.md b/doc/development/testing_guide/end_to_end/capybara_to_chemlab_migration_guide.md new file mode 100644 index 00000000000..9c7e0ef73a8 --- /dev/null +++ b/doc/development/testing_guide/end_to_end/capybara_to_chemlab_migration_guide.md @@ -0,0 +1,148 @@ +--- +stage: none +group: unassigned +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +--- + +# Migration Guide Capybara → Chemlab + +Given the view: + +*_form.html* + +```html +<form id="my-form"> + <label for="first-name">First name</label> + <input type="text" name="first-name" data-qa-selector="first_name" /> + + <label for="last-name">Last name</label> + <input type="text" name="last-name" data-qa-selector="last_name" /> + + <label for="company-name">Company name</label> + <input type="text" name="company-name" data-qa-selector="company_name" /> + + <label for="user-name">User name</label> + <input type="text" name="user-name" data-qa-selector="user_name" /> + + <label for="password">Password</label> + <input type="password" name="password" data-qa-selector="password" /> + + <input type="submit" value="Continue" data-qa-selector="continue"/> +</form> +``` + +| Capybara | Chemlab | +| ------ | ----- | +|  |  | + +<!-- +```ruby +# frozen_string_literal: true + +module QA + module Page + class Form < Page::Base + view '_form.html' do + element :first_name + element :last_name + element :company_name + element :user_name + element :password + element :continue + end + end + end +end +``` +```ruby +# frozen_string_literal: true + +module QA + module Page + class Form < Chemlab::Page + text_field :first_name + text_field :last_name + text_field :company_name + text_field :user_name + text_field :password + + button :continue + end + end +end +``` +--> + +## Key Differences + +### Page Library Design vs Page Object Design + +Page Objects as implemented in the existing framework require you to define methods to perform actions on elements. (Usually one-liners) + +```ruby +def set_first_name(first_name) + fill_element(:first_name, first_name) +end + +def click_continue + click_element(:continue) +end + +it 'sets first name and clicks continue' do + Page::Form.perform do |form| + form.set_first_name('First Name') + form.click_continue + end +end +``` + +Page Libraries make this more efficient by providing methods based on the page's elements, making extra methods unnecessary. + +```ruby +it 'sets first name and clicks continue' do + Page::Form.perform do |form| + form.first_name = 'First Name' # sets the first_name + form.continue # clicks Continue + end +end +``` + +Consider if we needed to validate the text of the `First name` field using Capybara. We'd need to add a one-liner to fetch the text: + +```ruby +def get_first_name + find_element(:first_name).text +end + +Page::Form.perform do |form| + form.set_first_name('First Name') + expect(form.get_first_name).to eq('First Name') + form.click_continue +end +``` + +Instead, because the page library automatically creates methods from page elements, we can fetch the text by calling `first_name` without writing code to define the method ourselves: + +```ruby +Page::Form.perform do |form| + form.first_name = 'First Name' + expect(form.first_name).to eq('First Name') + form.continue +end +``` + +### Element Naming Convention + +Since the element type is preserved within the Page Library, there is no need to specify a `_field` or `_button` suffix to the data-qa-selector. + +```html +<!-- Before --> +<input type="text" name="first-name" data-qa-selector="first_name_field" /> +<input type="submit" name="continue" value="Continue" data-qa-selector="continue_button" /> + +<!-- After --> +<input type="text" name="first-name" data-qa-selector="first_name" /> +<input type="submit" name="continue" value="Continue" data-qa-selector="continue" /> +``` + +This makes it much easier for Developers to write tests and contributes to testability since we can write the Page Library while we look at the UI. diff --git a/doc/development/testing_guide/end_to_end/img/gl-capybara_V13_12.png b/doc/development/testing_guide/end_to_end/img/gl-capybara_V13_12.png Binary files differnew file mode 100644 index 00000000000..9ceccd39025 --- /dev/null +++ b/doc/development/testing_guide/end_to_end/img/gl-capybara_V13_12.png diff --git a/doc/development/testing_guide/end_to_end/img/gl-chemlab_V13_12.png b/doc/development/testing_guide/end_to_end/img/gl-chemlab_V13_12.png Binary files differnew file mode 100644 index 00000000000..489a043f52e --- /dev/null +++ b/doc/development/testing_guide/end_to_end/img/gl-chemlab_V13_12.png diff --git a/doc/development/testing_guide/end_to_end/page_objects.md b/doc/development/testing_guide/end_to_end/page_objects.md index b124ac430f6..9ffa7ea4f77 100644 --- a/doc/development/testing_guide/end_to_end/page_objects.md +++ b/doc/development/testing_guide/end_to_end/page_objects.md @@ -260,7 +260,7 @@ These modules must: These steps ensure the sanity selectors check detect problems properly. For example, `qa/qa/ee/page/merge_request/show.rb` adds EE-specific methods to `qa/qa/page/merge_request/show.rb` (with -`QA::Page::MergeRequest::Show.prepend_if_ee('QA::EE::Page::MergeRequest::Show')`) and following is how it's implemented +`QA::Page::MergeRequest::Show.prepend_mod_with('Page::MergeRequest::Show', namespace: QA)`) and following is how it's implemented (only showing the relevant part and referring to the 4 steps described above with inline comments): ```ruby diff --git a/doc/development/testing_guide/end_to_end/running_tests_that_require_special_setup.md b/doc/development/testing_guide/end_to_end/running_tests_that_require_special_setup.md index ea48a3aa8b8..549ab95a5d1 100644 --- a/doc/development/testing_guide/end_to_end/running_tests_that_require_special_setup.md +++ b/doc/development/testing_guide/end_to_end/running_tests_that_require_special_setup.md @@ -147,10 +147,10 @@ docker rm gitlab-gitaly-cluster praefect postgres gitaly3 gitaly2 gitaly1 To run the Monitor tests locally, against the GDK, please follow the preparation steps below: -1. Complete the [Prerequisites](https://gitlab.com/gitlab-org/gitlab-development-kit/-/blob/master/doc/howto/auto_devops/index.md#prerequisites-for-gitlab-team-members-only), at least through step 5. Note that the monitor tests do not require permissions to work with GKE because they use [k3s as a Kubernetes cluster provider](https://github.com/rancher/k3s). +1. Complete the [Prerequisites](https://gitlab.com/gitlab-org/gitlab-development-kit/-/blob/main/doc/howto/auto_devops/index.md#prerequisites-for-gitlab-team-members-only), at least through step 5. Note that the monitor tests do not require permissions to work with GKE because they use [k3s as a Kubernetes cluster provider](https://github.com/rancher/k3s). 1. The test setup deploys the app in a Kubernetes cluster, using the Auto DevOps deployment strategy. -To enable Auto DevOps in GDK, follow the [associated setup](https://gitlab.com/gitlab-org/gitlab-development-kit/-/blob/master/doc/howto/auto_devops/index.md#setup) instructions. If you have problems, review the [troubleshooting guide](https://gitlab.com/gitlab-org/gitlab-development-kit/-/blob/master/doc/howto/auto_devops/tips_and_troubleshooting.md) or reach out to the `#gdk` channel in the internal GitLab Slack. -1. Do [secure your GitLab instance](https://gitlab.com/gitlab-org/gitlab-development-kit/-/blob/master/doc/howto/auto_devops/index.md#secure-your-gitlab-instance) since it is now publicly accessible on `https://[YOUR-PORT].qa-tunnel.gitlab.info`. +To enable Auto DevOps in GDK, follow the [associated setup](https://gitlab.com/gitlab-org/gitlab-development-kit/-/blob/main/doc/howto/auto_devops/index.md#setup) instructions. If you have problems, review the [troubleshooting guide](https://gitlab.com/gitlab-org/gitlab-development-kit/-/blob/main/doc/howto/auto_devops/tips_and_troubleshooting.md) or reach out to the `#gdk` channel in the internal GitLab Slack. +1. Do [secure your GitLab instance](https://gitlab.com/gitlab-org/gitlab-development-kit/-/blob/main/doc/howto/auto_devops/index.md#secure-your-gitlab-instance) since it is now publicly accessible on `https://[YOUR-PORT].qa-tunnel.gitlab.info`. 1. Install the Kubernetes command line tool known as `kubectl`. Use the [official installation instructions](https://kubernetes.io/docs/tasks/tools/). You might see NGINX issues when you run `gdk start` or `gdk restart`. In that case, run `sft login` to revalidate your credentials and regain access the QA Tunnel. @@ -272,7 +272,7 @@ You can free some memory with either of the following commands: `docker prune sy ## Geo tests -Geo end-to-end tests can run locally against a [Geo GDK setup](https://gitlab.com/gitlab-org/gitlab-development-kit/-/blob/master/doc/howto/geo.md) or on Geo spun up in Docker containers. +Geo end-to-end tests can run locally against a [Geo GDK setup](https://gitlab.com/gitlab-org/gitlab-development-kit/-/blob/main/doc/howto/geo.md) or on Geo spun up in Docker containers. ### Using Geo GDK |
