Docs: Adds best practices after visit and a link back to e2e.md (#21117)

* Docs: Adds best practices after visit and a link back to e2e.md in grafana-e2e

* Update contribute/style-guides/e2e.md

Co-Authored-By: Dominik Prokop <dominik.prokop@grafana.com>

* Update packages/grafana-e2e/README.md

Co-Authored-By: Dominik Prokop <dominik.prokop@grafana.com>

* Docs: Changes after PR comments

* Update contribute/style-guides/e2e.md

Co-Authored-By: Diana Payton <52059945+oddlittlebird@users.noreply.github.com>

* Update contribute/style-guides/e2e.md

Co-Authored-By: Diana Payton <52059945+oddlittlebird@users.noreply.github.com>

* Docs: Changes after PR comments

contribute/style-guides/e2e.md

@@ -58,11 +58,15 @@ Now that we have a `Page` called `Login` in our `Pages` const we can use that to
 
 The last step in our example is to use our `Login` page as part of a test. The `pageFactory` function we used before gives us two things: 
 - The `url` property is used whenever we call the `visit` function and is equivalent to the Cypress function [cy.visit()](https://docs.cypress.io/api/commands/visit.html#Syntax).
-- Any defined selector in the `selectors` property can be accessed from the `Login` page by invoking it and this is equivalent to the result of the Cypress function [cy.get(...)](https://docs.cypress.io/api/commands/get.html#Syntax).
+> Best practice after calling `visit` is to always call `should` on a selector to prevent flaky tests when you try to access an element that isn't ready. For more information, refer to [Commands vs. assertions](https://docs.cypress.io/guides/core-concepts/retry-ability.html#Commands-vs-assertions).  
+- Any defined selector in the `selectors` property can be accessed from the `Login` page by invoking it. This is equivalent to the result of the Cypress function [cy.get(...)](https://docs.cypress.io/api/commands/get.html#Syntax).
 ```ecmascript 6
 describe('Login test', () => {
   it('Should pass', () => {
     e2e.pages.Login.visit();
+    // To prevent flaky tests, always do a .should on any selector that you expect to be in the DOM.
+    // Read more here: https://docs.cypress.io/guides/core-concepts/retry-ability.html#Commands-vs-assertions
+    e2e.pages.Login.username().should('be.visible');
     e2e.pages.Login.username().type('admin');
   });
 });
@@ -129,11 +133,15 @@ When this list is rendered with the data sources with names `A`, `B`, `C` the re
 </div>
 ```
 
-Now we can go ahead and write our test and the one thing that differs from the `Basic example` is that we pass in which data source we want to click on as an argument to the selector function:
+Now we can write our test. The one thing that differs from the `Basic example` is that we pass in which data source we want to click on as an argument to the selector function:
+> Best practice after calling `visit` is to always call `should` on a selector to prevent flaky tests when you try to access an element that isn't ready. For more information, refer to [Commands vs. assertions](https://docs.cypress.io/guides/core-concepts/retry-ability.html#Commands-vs-assertions).  
 ```ecmascript 6
 describe('List test', () => {
   it('Clicking on data source named B', () => {
     e2e.pages.DataSources.visit();
+    // To prevent flaky tests, always do a .should on any selector that you expect to be in the DOM.
+    // Read more here: https://docs.cypress.io/guides/core-concepts/retry-ability.html#Commands-vs-assertions
+    e2e.pages.DataSources.dataSources('B').should('be.visible'); 
     e2e.pages.DataSources.dataSources('B').click();
   });
 });

packages/grafana-e2e/README.md

@@ -2,4 +2,4 @@
 
 > **@grafana/e2e is currently in ALPHA**. Core API is unstable and can be a subject of breaking changes!
 
-This package allows to run e2e tests
+This package contains an API wrapper built on top of [Cypress](https://www.cypress.io) that simplifies creating end-to-end tests for Grafana. More information can be found [here](https://github.com/grafana/grafana/blob/master/contribute/style-guides/e2e.md).