From e9647eb77424a25824c8fba292bf46d2bb28819d Mon Sep 17 00:00:00 2001 From: Tom Reece Date: Tue, 16 Jul 2019 10:07:18 -0500 Subject: [PATCH 1/5] MQE-1623: Add selector best practices to devdocs --- docs/selectors.md | 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+) create mode 100644 docs/selectors.md diff --git a/docs/selectors.md b/docs/selectors.md new file mode 100644 index 000000000..ea904e3ea --- /dev/null +++ b/docs/selectors.md @@ -0,0 +1,25 @@ +# Selectors + +The tips and tricks below will help you to write high quality selectors. + +### Selectors SHOULD be written in CSS instead of Xpath whenever possible. + +### Xpath selectors SHOULD NOT use `@attribute="foo"` instead you SHOULD use `contains(@attribute, "foo")` where `@attribute` is any attribute such as `@text` or `@class` for example. + +### CSS and Xpath selectors SHOULD be implemented in their most simple form. + +* GOOD: `#foo` +* BAD: `button[contains(@id, "foo")]` + +### CSS and Xpath selectors SHOULD avoid making use of hardcoded indices. Instead you SHOULD parameterize the selector. + +* GOOD: `.foo:nth-of-type({{index}})` +* BAD: `.foo:nth-of-type(1)` + +* GOOD: `button[contains(@id, "foo")][{{index}}]` +* BAD: `button[contains(@id, "foo")][1]` + +* GOOD: `#actions__{{index}}__aggregator` +* BAD: `#actions__1__aggregator` + +### CSS and XPath selectors MUST NOT reference the `@data-bind` attribute. \ No newline at end of file From 919fa05c36a08bdfe465b6bf3ff81c19c1ba4e52 Mon Sep 17 00:00:00 2001 From: Tom Reece Date: Wed, 17 Jul 2019 10:18:36 -0500 Subject: [PATCH 2/5] MQE-1623: Add selector best practices to devdocs - Fixed grammar --- docs/selectors.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/selectors.md b/docs/selectors.md index ea904e3ea..0da718629 100644 --- a/docs/selectors.md +++ b/docs/selectors.md @@ -4,7 +4,7 @@ The tips and tricks below will help you to write high quality selectors. ### Selectors SHOULD be written in CSS instead of Xpath whenever possible. -### Xpath selectors SHOULD NOT use `@attribute="foo"` instead you SHOULD use `contains(@attribute, "foo")` where `@attribute` is any attribute such as `@text` or `@class` for example. +### Xpath selectors SHOULD NOT use `@attribute="foo"`. Instead you SHOULD use `contains(@attribute, "foo")` where `@attribute` is any valid attribute such as `@text` or `@class`. ### CSS and Xpath selectors SHOULD be implemented in their most simple form. From 9658e3d41eac78a5b84ccc7b3860053188db83bf Mon Sep 17 00:00:00 2001 From: Donald Booth Date: Thu, 18 Jul 2019 09:41:03 -0500 Subject: [PATCH 3/5] Grammar and markdown --- docs/selectors.md | 18 +++++++++++------- 1 file changed, 11 insertions(+), 7 deletions(-) diff --git a/docs/selectors.md b/docs/selectors.md index 0da718629..8de1b0687 100644 --- a/docs/selectors.md +++ b/docs/selectors.md @@ -1,17 +1,21 @@ -# Selectors +## Selectors -The tips and tricks below will help you to write high quality selectors. +The guidelines below will help you to write high quality selectors. -### Selectors SHOULD be written in CSS instead of Xpath whenever possible. +### Selectors SHOULD be written in CSS instead of Xpath whenever possible -### Xpath selectors SHOULD NOT use `@attribute="foo"`. Instead you SHOULD use `contains(@attribute, "foo")` where `@attribute` is any valid attribute such as `@text` or `@class`. +### Xpath selectors SHOULD NOT use `@attribute="foo"`. -### CSS and Xpath selectors SHOULD be implemented in their most simple form. +Instead you SHOULD use `contains(@attribute, "foo")` where `@attribute` is any valid attribute such as `@text` or `@class`. + +### CSS and Xpath selectors SHOULD be implemented in their most simple form * GOOD: `#foo` * BAD: `button[contains(@id, "foo")]` -### CSS and Xpath selectors SHOULD avoid making use of hardcoded indices. Instead you SHOULD parameterize the selector. +### CSS and Xpath selectors SHOULD avoid making use of hardcoded indices + +Instead you SHOULD parameterize the selector. * GOOD: `.foo:nth-of-type({{index}})` * BAD: `.foo:nth-of-type(1)` @@ -22,4 +26,4 @@ The tips and tricks below will help you to write high quality selectors. * GOOD: `#actions__{{index}}__aggregator` * BAD: `#actions__1__aggregator` -### CSS and XPath selectors MUST NOT reference the `@data-bind` attribute. \ No newline at end of file +### CSS and XPath selectors MUST NOT reference the `@data-bind` attribute From b5e1939debe6ef98e62b37319b0f9662ba3527e0 Mon Sep 17 00:00:00 2001 From: Tom Reece Date: Mon, 22 Jul 2019 10:03:50 -0500 Subject: [PATCH 4/5] MQE-1623: Add selector best practices to devdocs - Add two descriptions - Changed all Xpath to XPath --- docs/selectors.md | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/docs/selectors.md b/docs/selectors.md index 8de1b0687..93178e2df 100644 --- a/docs/selectors.md +++ b/docs/selectors.md @@ -2,18 +2,20 @@ The guidelines below will help you to write high quality selectors. -### Selectors SHOULD be written in CSS instead of Xpath whenever possible +### Selectors SHOULD be written in CSS instead of XPath whenever possible -### Xpath selectors SHOULD NOT use `@attribute="foo"`. +CSS is often more succinct and natural to read. For example, `//*[@id="foo"]` in XPath can be expressed as simply as `#foo` in CSS. See this [XPath Cheatsheet](https://devhints.io/xpath) for more examples. + +### XPath selectors SHOULD NOT use `@attribute="foo"`. Instead you SHOULD use `contains(@attribute, "foo")` where `@attribute` is any valid attribute such as `@text` or `@class`. -### CSS and Xpath selectors SHOULD be implemented in their most simple form +### CSS and XPath selectors SHOULD be implemented in their most simple form * GOOD: `#foo` * BAD: `button[contains(@id, "foo")]` -### CSS and Xpath selectors SHOULD avoid making use of hardcoded indices +### CSS and XPath selectors SHOULD avoid making use of hardcoded indices Instead you SHOULD parameterize the selector. @@ -27,3 +29,5 @@ Instead you SHOULD parameterize the selector. * BAD: `#actions__1__aggregator` ### CSS and XPath selectors MUST NOT reference the `@data-bind` attribute + +The `@data-bind` attribute is used by KnockoutJS, a framework Magento uses to create dynamic Javascript pages. Since this `@data-bind` attribute is tied to a specific framework it should not be used for selectors. If Magento decides to use a different framework then these `@data-bind` selectors would break. From 386e7258a2d52d9c774b49b06100d79adc3faae2 Mon Sep 17 00:00:00 2001 From: Donald Booth Date: Mon, 22 Jul 2019 10:09:05 -0500 Subject: [PATCH 5/5] MInor fixes. --- docs/selectors.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/docs/selectors.md b/docs/selectors.md index 93178e2df..870072e15 100644 --- a/docs/selectors.md +++ b/docs/selectors.md @@ -1,13 +1,15 @@ ## Selectors -The guidelines below will help you to write high quality selectors. +These guidelines should help you to write high quality selectors. ### Selectors SHOULD be written in CSS instead of XPath whenever possible -CSS is often more succinct and natural to read. For example, `//*[@id="foo"]` in XPath can be expressed as simply as `#foo` in CSS. See this [XPath Cheatsheet](https://devhints.io/xpath) for more examples. +CSS is generally easier to read than XPath. For example, `//*[@id="foo"]` in XPath can be expressed as simply as `#foo` in CSS. +See this [XPath Cheatsheet](https://devhints.io/xpath) for more examples. ### XPath selectors SHOULD NOT use `@attribute="foo"`. +This would fail if the attribute was `attribute="foo bar"`. Instead you SHOULD use `contains(@attribute, "foo")` where `@attribute` is any valid attribute such as `@text` or `@class`. ### CSS and XPath selectors SHOULD be implemented in their most simple form @@ -30,4 +32,4 @@ Instead you SHOULD parameterize the selector. ### CSS and XPath selectors MUST NOT reference the `@data-bind` attribute -The `@data-bind` attribute is used by KnockoutJS, a framework Magento uses to create dynamic Javascript pages. Since this `@data-bind` attribute is tied to a specific framework it should not be used for selectors. If Magento decides to use a different framework then these `@data-bind` selectors would break. +The `@data-bind` attribute is used by KnockoutJS, a framework Magento uses to create dynamic Javascript pages. Since this `@data-bind` attribute is tied to a specific framework, it should not be used for selectors. If Magento decides to use a different framework then these `@data-bind` selectors would break.