Merge branch 'codeceptjs-v3.0' of github.com:codeceptjs/CodeceptJS into codeceptjs-v3.0

Author: DavertMik

docs/best.md

@@ -32,7 +32,7 @@ So if you want to click an element which is not a button or a link and use its t
 I.click(locate('.button').withText('Click me'));
 ```
 
-## Use Short Cuts
+## Short Cuts
 
 To write simpler and effective tests we encourage to use short cuts.
 Make test be focused on one feature and try to simplify everything that is not related directly to test.
@@ -60,8 +60,14 @@ Scenario('editing a metric', async ({ I, loginAs, metricPage }) => {
   I.see('Duration: Week', '.summary');
 });
 ```
+## Locators
 
-## Refactoring and PageObjects
+* If you don't use multi-lingual website or you don't update texts often it is OK to click on links by their texts or match fields by their placeholders.
+* If you don't want to rely on guessing locators, specify them manyally with `{ css: 'button' }` or `{ xpath: '//button' }`.  We call them strict locators. Those locators will be faster but less readable.
+* Even better if you have a convention on acive elements with special attributes like `data-test` or `data-qa`. Use `customLocator` plugin to easily add them to tests.
+* Keep tests readable whcih will make them maintainable.
+
+## Page Objects
 
 When a project is growing and more and more tests are required, it's time to think about reusing test code across the tests. Some common actions should be moved from tests to other files so to be accessible from different tests.
 
@@ -76,3 +82,156 @@ Here is a recommended strategy what to store where:
 
 However, it's recommended to not overengineer and keep tests simple. If a test code doesn't require reusage at this point it should not be transformed to use page objects.
 
+
+* use page objects to store common actions
+* don't make page objects for every page! Only for pages shared across different tests and suites.
+* use classes for page objects, this allows inheritace. Export instance of that classes.
+* if a page object is focused around a form with a multiple fields in it, use a flexible set of arguments in it:
+
+```js
+class CheckoutForm {
+  
+  fillBillingInformation(data = {}) {
+    // take data in a flexible format
+    // iterate over fields to will them all
+    for (let key of Object.keys(data)) {
+      I.fillField(key, data[key]); // like this one
+    }
+  }
+
+} 
+module.exports = new CheckoutForm();
+module.exports.CheckoutForm = CheckoutForm; // for inheritance
+```
+
+* for a components that are repeated accross a website (widgets) but doesn't belong to any page, use component objects. They are the same as page objects but focused only aroung one element:
+
+```js
+class DropDownComponent {
+  
+  selectFirstItem(locator) {
+    I.click(locator);
+    I.click('#dropdown-items li');
+  }
+
+  selectItemByName(locator, name) {
+    I.click(locator);
+    I.click(locate('li').withText(name), '#dropdown-items');
+  }
+}
+```
+* another good example is datepicker component:
+```js
+const { I } = inject();
+
+/**
+ * Calendar works
+ */
+class DatePicker {
+
+  selectToday(locator) {
+    I.click(locator);
+    I.click('.currentDate', '.date-picker');
+  }
+  
+  selectInNextMonth(locator, date = '15') {
+    I.click(locator);
+    I.click('show next month', '.date-picker')
+    I.click(date, '.date-picker')
+  }
+  
+}
+
+
+module.exports = new DatePicker;
+module.exports.DatePicker = DatePicker; // for inheritance
+```
+
+## Configuration
+
+* create multiple config files for different setups/enrionments:
+  * `codecept.conf.js` - default one
+  * `codecept.ci.conf.js` - for CI
+  * `codecept.windows.conf.js` - for Windows, etc
+* use `.env` files and dotenv package to load sensitive data
+
+```js
+require('dotenv').config({ path: '.env' });
+```
+
+* move similar parts in those configs by moving them to modules and putting them to `config` dir
+* when you need to load lots of page objects/components, you can get components/pageobjects file declaring them:
+
+```js
+// inside config/components.js
+module.exports = {
+    DatePicker: "./components/datePicker",
+    Dropdown: "./components/dropdown",
+}
+```
+
+include them like this:
+
+```js
+  include: {
+      I: './steps_file',
+      ...require('./config/pages'), // require POs and DOs for module
+      ...require('./config/components'), // require all components
+  },
+```
+
+* move long helpers configuration into `config/plugins.js` and export them
+* move long configuration into `config/plugins.js` and export them
+* inside config files import the exact helpers or plugins needed for this setup & environment
+* to pass in data from config to a test use a container:
+
+```js
+// inside codecept conf file
+bootstrap: () => {  
+  codeceptjs.container.append({
+    testUser: {
+      email: 'test@test.com',
+      password: '123456'
+    }
+  });
+}
+// now `testUser` can be injected into a test
+```
+* (alternatively) if you have more test data to pass into tests, create a separate file for them and import them similarly to page object:
+
+```js
+include: {
+  // ...
+  testData: './config/testData' 
+
+}
+```
+* .env / different configs / different test data allows you to get configs for multiple environments
+
+## Data Access Objects
+
+* Concept is similar to page objects but Data access objects can act like factories or data providers for tests
+* Data Objects require REST or GraphQL helpers to be enabled for data interaction
+* When you need to customize access to API and go beyond what ApiDataFactory provides, implement DAO:
+
+```js
+const faker = require('faker');
+const { I } = inject();
+const { output } = require('codeceptjs');
+
+class InterfaceData {
+
+  async getLanguages() {
+      const { data } = await I.sendGetRequest('/api/languages');
+      const { records } = data;
+      output.debug(`Languages ${records.map(r => r.language)}`);
+      return records;
+  }
+
+  async getUsername() {
+    return faker.user.name();
+  }
+}
+
+module.exports = new InterfaceData;
+```