Skip to content

Commit 24986ee

Browse files
popescunsergiupopescunsergiu
authored
Update README.md
1 parent 53acfbf commit 24986ee

File tree

1 file changed

+289
-2
lines changed

1 file changed

+289
-2
lines changed

‎README.md

Lines changed: 289 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,292 @@
1-
# ModusCreateOrg GitHub Guidelines
2-
This repository serves as a collection of useful scripts, configuration files, and settings for GitHub repositories.
1+
# Python Automation Boilerplate
2+
3+
## Description:
4+
This is a boilerplate for testing web & mobile hybrid apps on both iOS & Android.
5+
6+
### Dependencies:
7+
`Node` , `XCode` , `Android Studio`
8+
9+
### Installation Steps
10+
In order to get the tests to run locally, you need to install the following pieces of software:
11+
12+
#### MacOS
13+
1. `homebrew` - install using `ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"`
14+
2. `pyenv` - install using `brew install pyenv` This is a python version manager
15+
3. `python 2.7.6` - install using `pyenv install 2.7.6`
16+
4. `pyenv global 2.7.6` - Set python version 2.7.6 to be used globally
17+
18+
Add the following to *~/.bash_profile*
19+
```# Pyenv
20+
export PYENV_ROOT="$HOME/.pyenv"
21+
export PATH="$PYENV_ROOT/bin:$PATH"
22+
export PATH="$PYENV_ROOT/shims:$PATH"
23+
export PATH="$PYENV_ROOT/completions/pyenv.bash:$PATH"
24+
```
25+
5. `pytest` - install using `pip install pytest`
26+
6. `pytest_bdd` - install using `pip install pytest-bdd`
27+
7. `pylint` - install using `pip install pylint`
28+
8. `Appium-Python-Client` - install using `pip install Appium-Python-Client`
29+
9. `carthage` - install using `brew install carthage`
30+
10. This setup assumes that node is already installed on your system, if not please download the precompiled package from https://nodejs.org/en/download/ (select `Latest LTS Version`)
31+
11. `appium` - install using `npm install -g [email protected]` (Using v1.7.2 as this is the latest version ADF supports at this moment)
32+
12. SKIPPED. Not working on ADF. requests[security] - install using `pip install requests[security]`
33+
13. `pip install Faker future gherkin-official python-dateutil pyyaml requests retry`
34+
35+
### Windows
36+
1. TODOs
37+
38+
### Run all the tests locally
39+
In order to start the tests, you have to start Appium in another terminal window. To do that run ```appium```
40+
41+
The mobile application needs to be built (follow the steps from your project)
42+
43+
_Note_
44+
- for iOS builds take the _.app_ folder, and zip it, then enter the path to the zipped file in _conf_driver.py_
45+
- for Android builds, you should have the _.apk_ file available after running the _ionic cordova build android_ command
46+
47+
Then simply go to the _tests_root_ folder and run - `py.test -vv --gherkin-terminal-reporter --not_publish_results True`
48+
49+
Flag ```--not_publish_results True``` will make it sure that test runned locally will not be published to TestRail
50+
51+
### Run specific tests(feature) file
52+
Difference here is in listing *.feature* file, which will afterwards run only tests of those feature files listed.
53+
- Go to *tests_root/tests/constants.json*
54+
- Edit *suites* with feature file(s) you would like to run. eg:
55+
56+
- ```
57+
"project": {
58+
"id": 1,
59+
"name": "MC",
60+
"test_plan": "MC_Sprint_1",
61+
"env": "Apple iPhone 8Plus_iOS-11.0",
62+
"suites": {
63+
"calculator": "Calculator",
64+
"eula_welcome_screen": "EULA - Welcome Screen"
65+
},
66+
"tags":"",
67+
"language": "en",
68+
"market": "us"
69+
}
70+
71+
- After setting this up, you can run: `py.test -vv --gherkin-terminal-reporter --not_publish_results True`. But before that, read all of the below explained.
72+
- *suites* can contain a list of Test Suites (.feature files) to be added to the run and results publish
73+
74+
- Info:
75+
- **suites** = if empty all tests will be executed.
76+
- **tags** = further filtering
77+
- **language** = **mandatory**, taking string from i18n.json for selected language
78+
- **market** = **mandatory**, in order to know for which market to trigger tests
79+
### Run on real devices:
80+
#### iOS
81+
- `brew install libimobiledevice`
82+
- `npm install -g ios-deploy`
83+
84+
### Lint code
85+
Linting = the process of analyzing the source code to flag programming errors, bugs, stylistic errors, and suspicious constructs.
86+
87+
**IMPORTANT:** Lint your code before any commit
88+
89+
- Go to _tests_root_ folder
90+
- Run `pylint ./tests`
91+
- There should be only one Error: `E: 4, 0: invalid syntax (<string>, line 4) (syntax-error)`
92+
- This is due to a _pylint_ issue: root files or folders cannot be ignored from linting. Will follow the fix
93+
- A rating above 9.00 should be kept for the code
94+
95+
### Package tests for ADF
96+
**Prerequisites for ADF**: `constants.json` filled (See `Publish test results to TestRail` section and see `TestRail-Integration, Dependencies` section)
97+
1. Install Docker Community Edition from https://docker.com
98+
2. Go to _ubuntu_docker_ folder
99+
3. Create Docker from _ubuntu_docker_ folder
100+
1. `docker build -t ubuntu_01:v0.1 ./` - builds the docker image with name _ubuntu_01_
101+
2. `docker image ls -a` - lists all docker images
102+
- this should output 2 images one being _ubuntu_01_
103+
- to save the image `docker save ubuntu_01 > ubuntu_01.tar`
104+
- to load a saved image `docker load --input ubuntu_01.tar`
105+
3. `docker create -v [ABSOLUTE_PATH]/tests_root:/media/tests_root --name ubuntu_01 [DOCKER_IMAGE_ID]` - create docker container based on image
106+
4. `docker container ls -a` - lists all docker containers
107+
4. `docker start [DOCKER_CONTAINER_ID]` - starts docker container with id
108+
5. `docker exec -it [DOCKER_CONTAINER_ID] sh` - opens sh terminal within running docker container
109+
6. `cd media/tests_root`
110+
7. `sh package_tests.sh`
111+
112+
### TODOs
113+
- run pytest with parameters - tags
114+
115+
116+
# TestRail-Integration
117+
This is HOW TO guide for TestRail integration of this project
118+
119+
### Configuration:
120+
Add TestRail API credentials to `./tests_root/tests/constants.json` file
121+
122+
```
123+
"testrail": {
124+
"user_email": "",
125+
"user_key": "",
126+
"url": "https://[SUBDOMAIN].testrail.io",
127+
"verify_ssl": "true"
128+
}
129+
```
130+
131+
Note: Please follow instructions for generating user_key: http://docs.gurock.com/testrail-api2/accessing
132+
133+
**!DO NOT PUSH your credentials into git repo**
134+
135+
### Publish test cases to TestRail
136+
- Go to *tests_root/*
137+
- Run:
138+
139+
**To import/update test Scenarios for ALL feature files**
140+
- ```py.test -vv --not_publish_results True --publish True --object_path "tests/features"```
141+
142+
**To import/update test Scenarios for INDIVIDUAL .feature file**
143+
- ```py.test -vv --not_publish_results True --publish True --object_path "tests/features/[FILE_NAME].feature"```
144+
145+
### Implementation details
146+
- Each *.feature* file is a product functionality
147+
- Unique key is the pair of **feature name** + **feature description**
148+
```gherkin
149+
Feature: End User License Agreement (EULA)
150+
As a Quitter
151+
I open the app for the first time
152+
I want to be able to view and accept the terms and conditions and privacy policy.
153+
```
154+
- It will create a new **test suite** for each *.feature* file published
155+
- If **test suite** was imported it will update all the tests within
156+
- Each *Scenario* is a TestRail *case*
157+
- Unique key is pair of **scenario name** + **data set** (The Examples line in json format)
158+
```gherkin
159+
Scenario: Add two numbers
160+
Given I have powered calculator on
161+
When I enter <50> into the calculator
162+
When I enter <70> into the calculator
163+
When I press add
164+
Then The result should be <120> on the screen
165+
Examples:
166+
| number_1 | number_2 | result |
167+
| 10 | 20 | 30 |
168+
| 50 | 60 | 120 |
169+
```
170+
- It will create a new **case** for each *Scenario* published
171+
- If **case** was imported it will update it with latest changes
172+
- Scenario *tags*:
173+
- **@automation** = **case** is automated
174+
- **@LWH-1** = **case ref** to Jira ticket (the feature ticket)
175+
- **@smoke** / **@sanity** / **@regression** / **None** = **case priority** Critical / High / Medium / Low
176+
- **@market_us** = **case** is for USA market
177+
- **@not_market_ca** = **case** is not for Canada market
178+
- *Steps* are imported as separate ones with empty *Expected Results*
179+
- Do **NOT** use *And* and *But* keys as it will fail the match of test cases during results publishing
180+
181+
### Publish test results to TestRail
182+
####Prerequisites:
183+
##### 1. Create Test Plan in TestRail
184+
- You have to manually create the test plan in TestRail
185+
- Naming convention: [JIRA_PROJECT_NAME]_[SPRINT_NAME]_[MARKET]
186+
- eg: *LWH_Sprint-1_us* or *LWH_Regression_us*
187+
- Test Plan can be empty
188+
- Automated tests will create Test Runs for each Test Suite that exists and is in scope of testing: See: *project.suites*
189+
- Test Run name: [TEST_SUITE_NAME] [ENV]
190+
- eg: *EULA - Welcome Screen iPhone8_iOS-11.4*
191+
- If Test Run is present it will only add a new set of results with the current timestamp
192+
- Test results are published to TestRail at the end of testing
193+
- The reason of failure is also added to the test step
194+
195+
##### 2. Test run details in `project`
196+
- Go to *tests_root/tests/constants.json*
197+
- Edit *project* with corresponding data. eg:
198+
- ```
199+
"project": {
200+
"id": 1,
201+
"name": "LWH",
202+
"test_plan": "LWH_Sprint_1",
203+
"env": "Apple iPhone 8Plus_iOS-11.0",
204+
"suites": {
205+
"calculator": "Calculator",
206+
"eula_welcome_screen": "EULA - Welcome Screen"
207+
},
208+
"tags":"",
209+
"language": "en",
210+
"market": "us"
211+
}
212+
- *suites* can contain a list of Test Suites (.feature files) to be added to the run and results publish
213+
- If *suites* is left empty then all the available suites (.feature files) will be ran and results published for that environment
214+
215+
- Info
216+
- **id** = **mandatory**, taken from TestRail, is the id of the project. Can be picked up from url in TestRail. Make sure id is correct.
217+
- **name** = **mandatory**, name of the project you will publish to.
218+
- **test_plan** = **mandatory**, title of the test plan created manually in TestRail
219+
- **env** = **mandatory**, device name that will be displayed upon published test run result
220+
- **suites** = if empty all tests will be executed.
221+
- **tags** = further filtering
222+
- **language** = **mandatory**, taking string from i18n.json for selected language
223+
- **market** = **mandatory**, in order to know for which market to trigger tests
224+
225+
##### Run test locally and publish to TestRail
226+
- Go to *tests_root/*
227+
- Run:
228+
- ```py.test -vv --gherkin-terminal-reporter``` - this will run and publish tests results
229+
- **NOTE:** To avoid publishing results (for local scope) ```py.test -vv --gherkin-terminal-reporter --not_publish_results True```
230+
231+
232+
## Notes
233+
### Tips and Tricks
234+
To benefit from autocomplete please set *tests_root* folder as **Sources Root**
235+
- Right click on *tests_root_*
236+
- Click on *Mark Directory As*
237+
- Click on *Sources Root*
238+
239+
### Installation issues
240+
In case you run in any issues with the above steps below are a set of tips for common problems:
241+
242+
- chromedriver errors while installing appium use:
243+
- `npm install -g [email protected] --unsafe-perm=true --allow-root`
244+
- If installation fails and it asks for a _sudo_, you can type following (_sudo_ is not recommended):
245+
- 1st reinstall _homebrew_
246+
```
247+
brew cleanup
248+
brew uninstall --force
249+
```
250+
- 2nd reinstall _appium_
251+
```
252+
npm uninstall -g appium
253+
npm install -g appium-doctor
254+
npm install -g [email protected]
255+
appium-doctor //checks your appium installation
256+
```
257+
- 3rd if none of the above work then you can try the following
258+
```
259+
sudo chown -R $USER ~/.npm
260+
sudo chown -R $USER /usr/lib/node_modules
261+
sudo chown -R $USER /usr/local/lib/node_modules
262+
```
263+
264+
#### Setup $JAVA_HOME
265+
- Install latest _Java 8_
266+
- use your preferred text editor (nano, vim, etc) and edit .bash_profile with the following
267+
- paste the following two lines:
268+
```
269+
export JAVA_HOME=$(/usr/libexec/java_home)
270+
export PATH=$JAVA_HOME/bin:$PATH
271+
```
272+
- save the change
273+
- type `source .bash_profile` to make the changes available in the current terminal session
274+
- To verify in console type, `echo $JAVA_HOME`. It should display `/System/Library/Java/JavaVirtualMachines/1.X.X.jdk/Contents/Home`. Second way to verify is to type `appium-doctor`
275+
276+
#### Setup ANDROID_HOME
277+
- Install _Android Studio_
278+
- Open _Android Studio_ and install all dependencies
279+
- use your preferred text editor (nano, vim, etc) and edit _.bash_profile_ with the following
280+
- paste the following three lines (change username on first line and Android install location if it is not the default one):
281+
```
282+
export ANDROID_HOME=/Users/[USERNAME]/Library/Android/sdk
283+
export PATH=$ANDROID_HOME/platform-tools:$PATH
284+
export PATH=$ANDROID_HOME/tools:$PATH
285+
```
286+
- save the change
287+
- type `source .bash_profile` to make the changes available in the current terminal session
288+
- run `appium-doctor` to verify it looks good
289+
3290
4291
> Modus Create team members should refer to [ModusCreateOrg GitHub Guidelines](https://docs.google.com/document/d/1eBFta4gP3-eZ4Gcpx0ww9SHAH6GrOoPSLmTFZ7R8foo/edit#heading=h.sjyqpqnsjmjl)
5292

0 commit comments

Comments
 (0)