From 5fee20fe4e6c79380a62f6bd3ecff50003fe117a Mon Sep 17 00:00:00 2001 From: Mark Lapierre Date: Thu, 12 Sep 2019 00:09:02 +0000 Subject: Make block arg naming more flexible --- .../testing_guide/end_to_end/style_guide.md | 40 +++++++++++++++++----- 1 file changed, 31 insertions(+), 9 deletions(-) diff --git a/doc/development/testing_guide/end_to_end/style_guide.md b/doc/development/testing_guide/end_to_end/style_guide.md index 54ed3f34c89..2b9f374df6a 100644 --- a/doc/development/testing_guide/end_to_end/style_guide.md +++ b/doc/development/testing_guide/end_to_end/style_guide.md @@ -101,44 +101,66 @@ end ## Block argument naming -To have a standard on how we call pages when using the `.perform` method, we use the name of page object being called, all lowercased, and separated by underscore, if needed (see good and bad examples below.) This also applies to resources. We chose not to simply use `page` because that would shadow the Capybara DSL, potentially leading to confusion and bugs. +To have a standard on what we call pages and resources when using the `.perform` method, +we use the name of page object in [snake case](https://en.wikipedia.org/wiki/Snake_case) +(all lowercase, with words separated by an underscore). See good and bad examples below. + +While we prefer to follow the standard in most cases, it is also acceptable to +use common abbreviations (e.g., mr) or other alternatives, as long as +the name is not ambiguous. This can includeg appending `_page` if it helps to +avoid confusion or make the code more readable. For example, if a page object is +named `New`, it could be confusing to name the block argument `new` because that +is used to instantiate objects, so `new_page` would be acceptable. + +We chose not to simply use `page` because that would shadow the +Capybara DSL, potentially leading to confusion and bugs. ### Examples **Good** ```ruby -# qa/specs/features/browser_ui/1_manage/project/add_project_member_spec.rb - Page::Project::Settings::Members.perform do |members| members.do_something end ``` ```ruby -# qa/specs/features/ee/browser_ui/3_create/merge_request/add_batch_comments_in_merge_request_spec.rb - Resource::MergeRequest.fabricate! do |merge_request| merge_request.do_something_else end ``` -**Bad** +```ruby +Resource::MergeRequest.fabricate! do |mr| + mr.do_something_else +end +``` ```ruby -# qa/specs/features/browser_ui/1_manage/project/add_project_member_spec.rb +Page::Project::New.peform do |new_page| + new_page.do_something +end +``` + +**Bad** +```ruby Page::Project::Settings::Members.perform do |project_settings_members_page| project_settings_members_page.do_something end ``` ```ruby -# qa/specs/features/ee/browser_ui/3_create/merge_request/add_batch_comments_in_merge_request_spec.rb - Resource::MergeRequest.fabricate! do |merge_request_page| merge_request_page.do_something_else end ``` +```ruby +Page::Project::New.peform do |page| + page.do_something +end +``` + > Besides the advantage of having a standard in place, by following this standard we also write shorter lines of code. -- cgit v1.2.3