Environment Setup

Overview:
The RDM Automation Framework is a web application built utilizing Angular, Typescript, HTML, CSS, Node, and Python. The application is currently
hosted on a Heroku web server, and the staging version can be viewed at

qa-rdm-staging.herokuapp.com

Current features of the site are as follows:

A scheduling webpage containing a scheduler which is used as a means of running jobs. These jobs can be python test scripts that both don’t
and do require selenium to run, along with postman collections. Jobs can be configured to run periodically where you can specify how often you
would like the selected script(s) to run.

Ex. You can specify scripts to run once a day or every day at specific time

A results-gathering mechanism which will record the number of test cases passed, failed and any other errors that have occurred when a specific
job has executed. This information will be aggregated and displayed in the form of a table on a results webpage where users will be able to
traverse through all results for any test-cases that have ran.

A Dashboard webpage which will display the weekly and daily passes and fails of scripts which are a part of a specific brand (ex. Breakfast-
Television, City Tv)
 A User Management portal that is only available to those with the admin role. It will allow admins to modify permissions/roles of users, change
users passwords, and delete users who have an account registered with the framework.

A notification service that will send an email to the user should they provide it when creating their job to run. This email will contain the results of
their scheduled job including the scripts ran. For each script it lists the number of passes, failures, errors and a details link that links back to the
framework where the user can view more details about the errors or failures if there were any. The email also contains a Failed Scripts section for
any scripts that have failed during the middle of their execution, and provides the error that they failed with.

To get a better idea of the kind of scheduled test scripts for each brand that run frequently look in the following repo: https://github.com/digitalmedia/QA/tree
/master/Selenium%20Scripts

Note: if you do not have access to the repo, you will need to ask either your manager to gain access or another member of your team
who already has access

Check the end of this document to see a list of useful resources for any issues that occur while going through the step-by-step process
Local Environment Setup:
(Creating a local copy of the RDM framework using the selenium grid on your machine so you can create new features here before pushing to the staging
environment/ selenium grid)

Requirements before starting:

-Create a Heroku account:

-Go to https://id.heroku.com/login

-Create a Github account:

-Go to https://github.com/

Note: If at any point in this setup process nothing is installing, do a restart and then attempt to continue in the setup process

1. Install Homebrew (a free and open-source software package management system that will install applications such as Node, Postgres and others
without having to directly download from their sites) from the following below:
a. Go to https://brew.sh/ and follow the installation instructions
b. Open up a terminal session and paste the following command

i. This removes the checks originally done with permission

Note: If brew has been installed properly, going forward any issues involving software using brew, enter the following command in your
terminal:

a. $ brew doctor

i. This is meant to provide suggestions on how to fix issues installing packages. It will not fix every issue but, it is an
invaluable resource to look at.

2. Install Heroku CLI from the either of the following ways below:

a. Go to https://devcenter.heroku.com/articles/heroku-cli#download-and-install

b. Open up a terminal session and paste the following command provided that Homebrew is properly installed:

3. Install Git CLI from either of the following ways below:

a. Go to https://git-scm.com/download/

b. Open up a terminal session and paste the following command provided that Homebrew is properly installed:

4. Verify that Heroku, Git and brew are installed by typing the following commands:

a. heroku –version

b. git –version

c. brew –version

5. Close all other terminal sessions running. Open a new terminal session and login using the following steps:

a. $ cd Desktop

b. $ heroku login -I

i.Email: (your Heroku email you registered)

ii. Password: (password of email you registered)

 **Please read summary under command

c. $ heroku git:clone -a qa-rdm-staging

i. This command pulls all files of the framework currently running in the staging application onto your local machine using git. This is
great for a first time setup to see how the app works locally, but once you start actually developing code for it, it is better to work off of
the QA repo and download the code from there. This way you are able to manage all of the different branches and push and pull the
latest changes that others have made without deploying each time.

6. Install node(npm) & its dependencies (this will allow you to run a local server to run the framework)

a. To install npm run the following commands sequentially:

NOTE: At any point while running the following npm install commands DO NOT run 'npm audit fix' as that will modify package
version and unlink dependencies which will cause the framework to not install properly.

i. $ brew install node

ii. $ npm install -g ts-node

iii. $ npm install -g n

iv. $ sudo n 10.16

v. $ npm -v && node -v && ts-node -v

*Verify that you have the same or similar versions as output. If you run into version problems later anywhere during the
instillation try installing these exact ones as they have been tested.

b. You need to install more node dependencies in the framework’s root directory. The root directory is the folder that was created on your
desktop when running the Heroku git: clone command. In this particular case it is qa-rdm-staging. Go into the root directory of the framework:
 i. $ cd qa-rdm-staging

-Once inside run, the following command:

ii. $ npm install -g @angular/cli

-This is to install only the angular command line interface globally

c. Install all packages specified in package.json with the following command in the root directory:

i. $ npm install

-Your root directory should now have a node_modules folder installed:

7. Creating a local copy of the postgres database used to store results, test_cases, etc. and populate it with data from Heroku. This will allow your
local version of the framework have access to a local version of the database to in order to function properly. To accomplish this the following must
be done:

a. Go to your framework’s root directory if you haven’t already:

i. $ cd qa-rdm-staging

b. Install the postgres software through brew:

i. $ brew install postgresql

Run the cmd: $ psql -V to check that postgres is installed (Make sure it version 11 or 11.5 or 11.7 that is installed and not 12 or
further.

Note: If you run the following command and receive any errors, one reason might be because in some instances, you may have to manually
start the postgres server through the command line before you can execute the Heroku command. To start the server manually you can do it
using either of the following methods:

$ brew services start postgresql (Provided that it was installed using brew)
$ pg_ctl -D /usr/local/var/postgres start (Provided that the postgres folder is in that location)

ii. $ heroku pg:pull postgresql-dimensional-23074 (database name of your choosing) --app (root directory name)

This cmd will pull the data from Heroku and populate it into the table. Below is an actual example:

To view the actual database, run the following cmd:

 $ psql (database name) (In this case it would be $ psql localDb. You should receive the following. To view the tables in the database type $
\dt. To quit the database, type $\q. Below is an example of the expected outputs)

8. Install Python and its dependencies such as pip3:

a. Install python3 from the following methods provided:

i. $ brew install python3 or $ brew install python

ii. Go to https://realpython.com/installing-python/ and follow the instructions on the website to install

b. As you have installed python3, then pip3 should be made available. Check the version using step 8c). If it is not installed attempt installing
manually using either of the following methods.

i. $brew install pip3

ii. Go to https://www.makeuseof.com/tag/install-pip-for-python/ and follow the instructions on the website to install

c. Verify that both pip3 and python3 are install on your machine by typing in the following:

i. $ python3 –version && pip3 –version

 d. Now that pip3 is installed, you will need to make sure that the required dependencies are also installed. To do so you will need to run the
following commands:

i. $ cd ~/Desktop/qa-rdm-staging/

ii. $ pip3 install -r requirements.txt

9. Provided that you have followed all the steps up until this point and all expected outcomes have been achieved, you will now have to setup
environment variables. Environment variables are stored in your bash_profile. To go into your bash_profile, go to your terminal and enter either:

a. $ vim ~/.bash_profile

b. $ nano ~/.bash_profile

Here is a list of all the environment variables used by the framework, along with a description:

RDM_URL: The is is the url of the server that is the framework is being run on.

ex: http://localhost:8080 | note: do not include '/' at the end of url

DATABASE_URL: The database url of the database being used with the framework. In your case it will be the one that you cloned down
earlier in the setup document.

ex: <dbtype>://<dbuser>:<dbpass>@<host>:<port>/<dbname>

*Notes: dbtype=postgres, host=localhost and the default port for postgres is 5432. The rest of the fields in "<>" need to be replaced
with your postgres instance's values.

dbuser is account the name of the account you are logged in as on your machine. dbpass can be anything unless your
database is password enforced, which is shouldn't be by default, and dbname is the same value as you chose in step 7.

SELENIUM_GRID_URL: The client url of the selenium grid that you want the framework to run selenium tests on. (optional if no selenium
tests are being ran)

ex: http://localhost:4444/wd/hub

CLOUD_CREDENTIAL_USER: This is the email account that is being used to send all emails out from the rdm framework. This includes
functions such as sending emails containing jobs to the local grid so they can run there, as well as sending notification emails when jobs are
finished running. This email account should be a gmail one and requires: less secure app access, IMAP enabled, and an app password.

ex: herokuuser2019@gmail.com

CLOUD_CREDENTIAL_PASS: This is password for the cloud credential user (email). It should be a gmail app password as to avoid issues
when running in a cloud environment.

ex: vxwdfeyyyyeekvrjhm

LOCAL_CREDENTIAL_USER: This is the email account to which you want the framework to send all locally scheduled jobs to. This should
be the same as the email account that is being used by the grid controller module if you are running the framework in connection with a
selenium local grid that is using the module. More info on this can be found here: https://github.com/digitalmedia/QA/tree/grid-controller

ex: rdm.development.grid@gmail.com

GITHUB_CONNECTION_URL: This is the Github url for the repo that contains all of the framework test scripts that it can run.
 ex: https://QAAutomationFramework:5519baf3ea7e6be517b10690eb01b6ab19c4c99c@github.com/digitalmedia/QA.git

AUTH_DOMAIN: The domain for the auth0 application instance. In our current case it is the auth0 NATIVE application RDM Framework local.

ex: https://dev-ka6176f8.auth0.com

AUTH_AUDIENCE: The url of the server that you are going to be running the framework on, or where the audience you are serving will go to
access the application.

ex: http://localhost:8080

MANAGEMENT_API_CLIENT_ID: This is the auth0 client id for the machine to machine application created to interact with the auth0
management api. In our case the local app for this used during development is management-api-qa-rdm-local.

MANAGEMENT_API_CLIENT_SECRET: This is the auth0 client id for the machine to machine application created to interact with the auth0
management api. (management-api-qa-rdm-local)

APP_CLIENT_ID: The client ID from the auth0 Native application, which in our case is RDM Framework local.

APP_CLIENT_SECRET: The client Secret from the auth0 Native application, which in our case is RDM Framework local.

Below are example values for you to copy into your bash profile:

* Note that you may have to change some of these values, mainly the database_url to match your newly created database back in
step 7. And the local credential user, if you are using the framework in connection with a grid controller instance.

________________________________________________________________________________________________________________
________________________________________________________________________________________________________________
__________

export RDM_URL=http://localhost:8080

export DATABASE_URL=postgres://rdmtester:testpass@localhost:5432/rdmdb

export SELENIUM_GRID_URL=http://localhost:4444/wd/hub

export CLOUD_CREDENTIAL_USER=herokuuser2019@gmail.com

export CLOUD_CREDENTIAL_PASS=vxweevvvveekvjhm

export LOCAL_CREDENTIAL_USER=rdm.development.grid@gmail.com

export GITHUB_CONNECTION_URL=https://QAAutomationFramework:5519baf3ea7e6be517b10690eb01b6ab19c4c99c@github.com
/digitalmedia/QA.git

export AUTH_DOMAIN=https://dev-ka6176f8.auth0.com

export AUTH_AUDIENCE=http://localhost:8080

export MANAGEMENT_API_CLIENT_ID=U8lGDZ06uR6qDaCjGeEAZ730CagskxVS

export MANAGEMENT_API_CLIENT_SECRET=eD3CvBkItSnQkx0UZ96vRFZZZ47_b6lJNi8pLKMyaEYxrtXqYy5FLLc_cLAzvAZ3

export APP_CLIENT_ID=JTkGPTlqtToTMNDWGD7y3E16hkKoymVW

export APP_CLIENT_SECRET=Kd-AvufQqJGIg1-FmpOMYvy31EWI6wsUBm4cBZ-V3LbLfju0qJ4USAgpU7HkX64O
Note: your bash_profile should look like the following:

Also, depending on if you are receiving any errors with the installation of postgres, include the variables CPPFLAGS AND LDFLAGS where the
values of these variables will be location of postgres folder

14. Save your bash_profile and exit the file. Close all terminal sessions as the only way for the variables to be recognized in the bash_profile
is by closing all sessions.

Starting up the environment:

-Provided that all steps previously have been followed and are yielding the expected results, you will now be able to startup your environment. To
start the environment you will need to do the following:

1. Go to your app’s (qa-rdm-staging file) root directory with the following command on your terminal

a. $cd ~/Desktop/qa-rdm-staging

2. Start the server using either of the following methods:

a. $npm run serverlocal

i. This command starts the server and scheduler, but will not rebuild the project/application so any changes made to client side code
will not take effect.

b. $npm run startlocal

i. This command starts the server and scheduler, and will rebuild the project/application so any changes made to the client side will
take effect!

Note: any changes that are made to the files in the framework(ex. Editing html files, css files, .ts files) will require you to stop the framework
with entering $ ^C (ctrl + c) and then restarting the server using command b.

Running Test Scripts on the Framework:

All of our scripts are running using either of the following methods:

A selenium grid, which utilizes machines configured as hubs and nodes, where the hub passes the jobs to the node to run. In our office this can
be run locally on your personal machine or we have a setup of multiple laptops where one machine is the hub and it will send jobs to the rest of
the nodes. The latter model is what is being used at the moment for the production version of the framework.
On the cloud, which is using Browserstack for any selenium scripts and newman cli for any postman collections

Setting up a selenium grid to run scripts from the repo on your local
machine:
1. Install selenium for python:
a. $ cd ~/Desktop/
b. $ pip3 install selenium
 2. Download the selenium standalone server. The scripts are run using a hub and node model where a hub will send jobs containing scripts to a
node that will execute the job. To read more information on this model click the following link: http://www.joecolantonio.com/selenium-grid-how-to-
setup-a-hub-and-node/

i. Link to download Selenium Standalone Server: http://docs.seleniumhq.org/download/ , move this jar file to your desktop

3. Download drivers and add them to your system path. You can add the locations to the path in your /.bash_profile. Use the following image as
a reference on how to add on your /.bash_profile.

These drivers are utilized for running scripts on each type of browser, the following links are to install drivers for firefox and chrome:

a. Firefox (Gecko Driver): https://github.com/mozilla/geckodriver/releases

b. Chrome (ChromeDriver): https://sites.google.com/a/chromium.org/chromedriver/downloads

4. Configure the hub and node by running the following commands on separate terminal windows (ensure you are in the same directory as your jar file).

*Note: Without this step you can still be able to run the cmd: `$npm run startlocal` inside your framework’s root directory and be able to
view the framework. However, you will not be able to run scripts requiring selenium. Thus, it is convenient to run this step only when you
have selenium scripts to schedule as it takes time to setup the hub, node and npm run startlocal together:

a. Hub: $ java -jar selenium-server-standalone-3.141.59.jar -role hub

i. You can setup a timeout on the hub so that if any script running encounters an error that causes the script to run continuously with
no stopping, this timeout will close the hub and node, which is stop the script execution. The timeout is in seconds (600 = 10 mins,
1200 = 20 mins).

$ java -jar selenium-server-standalone-3.141.59.jar -role hub -timeout 1200

b. Node: java -jar selenium-server-standalone-3.141.59.jar -role node -hub http://localhost:4444/grid/register

Hub Window:

Node Window:

5. Configure scripts to use local drivers:

a. Navigate to your environment variables and set the SELENIUM_GRID_URL to the client url of the selenium grid server.

a. Navigate to and open /Users/rdmtester/Desktop/lastframework/rdmframework/src/scheduler/selenium_scripts/setup/config.py

b. Set the command_executor variables (near the bottom of the file) to your local hub Client URL:

i. Ex: http://192.168.0.14:4444/wd/hub (as seen in the above hub screenshot)

ii. Or http://localhost:4444/wd/hub

Ex. Go to QA/testScript.py in the QA_Scripts branch to see an example of a simple script that opens a driver which will then
attempt to log into facebook.com. This script has been configured to run with the scheduler:

6. Schedule a job

a. Open up the RDM framework and go to the scheduler

b. Click ‘Create’ at the top left

c. Schedule a job to run at a desired time (Note: If the current time is 11:10am, the earliest job you can create would be 11:11am)
 d. Make sure to use CLOUD for platform and list the file name of any test script(s) from rdm-framework/src/scheduler/selenium_scripts
/QA_Scripts or the QA_Scripts GitHub repo, as that is where it pulls from.

7. Click ‘Submit’. Refer to the Troubleshooting section at the end of this guide if a script does not appear within 30 seconds from the scheduled time
and check the terminal session running the framework for any error messages.

8. Once you have seen that a script has finished executing, check the Results page on the framework to see if a new result has been added

9. You’ve successfully run a script locally! Note: Do not click or interrupt an automated browser instance as this may interfere with the test script
execution and produce inaccurate results

NOTE: If the script does not execute, it might be because chromedriver and geckodriver were either not installed properly or added to the
path properly. You can as an alternative run the following commands to install chromedriver and geckodriver:

i. $ brew install chromedriver followed by $ brew cask install chromedriver

ii. $ brew install geckodriver

Other methods to run scripts:

 Using the grid setup – in your environment variables set the SELENIUM_GRID_URL to the local grid client URL and make sure that you are
connected through ethernet. If successful, you can see the script running on the grid machines.
Using Browserstack – in your environment variables set the SELENIUM_GRID_URL to a Browserstack hub URL

Setting up pulling and pushing changes from github:

From Command Line:

Pulling Changes from GitHub:

a. Navigate into the QA repo you created during your local environment setup.

b. If you are trying to create a local copy of the repo on your machine for the first time try the following command in your preferred
location for the repo:

i. $ git clone <web url of repo> For example: $ git clone https://github.com/digitalmedia/QA.git

c. If you have made minimal changes to your local copy of the framework then try:

i. $ git pull

d. If `git pull` fails or you have made a decent amount of changes to your local copy, then run this sequence of commands:

i. $ git stash

ii. $ git pull

iii. $ git stash pop

*Note that once you pop the stash you must then go through all files with merge conflicts and manually either accept or decline the changes to
them before you are able to push to the repo again.

Pushing Changes to GitHub:

a. Run $ git status to get an overview of what files have been modified and are different than the versions currently on the GitHub
origin repo

b. Use the $ git add <filename> command to stage all the files you wish to commit to the repo.
***Note: Special considerations must be taken when adding these specific files: config.py

i. Make sure that the default and desired `SELENIUM_GRID_URL` fields in the file are set to the browserstack URL

c. Run the following commands which will commit the changes (aggregate all files that have changes made to them into one location)
and then push them to your repo:

i. $ git commit –m “<insert commit message>”

ii.$ git push

From Github Desktop:

a. Download Github Desktop from the following link: https://desktop.github.com/

b. Follow the instructions to add or clone repositories on github desktop: https://help.github.com/en/desktop/contributing-to-projects/adding-

and-cloning-repositories

Deploying to Heroku
*Note: these changes made will only show up if you push changes to github through the terminal or command line

1. In your terminal, in the QA repo go to the branch you want to push changes to.
2. Login to heroku using: $ heroku login -i and enter your heroku email and password
3. Run the cmd: $ git add . to capture any changes made to file within the branch
4. Run the cmd: $ git commit -m "message here to show on github" to commit changes to the branch
5. Run the cmd: $ heroku git:remote -a <appName> so in this case the appname is qa-rdm-staging so $ heroku git:remote -a qa-rdm-staging
6. Run the cmd: $ git remote -v to check that the remote called heroku is added
7. Run the cmd: $ git push -f heroku <branch-name>:master to deploy to the app you selected. In this case it will be $ git push -f heroku rdm-
framework-production:master

Below is a demonstration of the commands above:

 If you want any other information on deploying check the following link: https://stackoverflow.com/questions/18406721/heroku-does-not-
appear-to-be-a-git-repository

*Note: you may have to set up a new git Heroku remote for this step to work if it has not automatically been done when you cloned the repo.

3. If the build fails, use the logs that show up on the terminal screen to debug and guide any changes that may need to be made. Note that if changes
must be made in the source code, you need to push them to the repo branch again, for them to take effect.

4. Once the app is deployed you can use <Heroku logs --tail> to view the logs stream and monitor all app activity. It is a good habit to always do this
right after a deploy to ensure services have started up correctly and no errors have occurred during the process.

5. Other useful commands are <heroku run bash> for getting a bash copy of the file system and <heroku pg:psql postgresql-cubic-68015 --app rdm-
framework> for accessing the database. If either command doesn’t work try running <heroku login> first.

Steps for integrating new database tables into rdm application

1. Create an entity file (should match column names and order of your table exactly!)
a. Do so by running the following command (in an empty directory - otherwise current entity files may be overwritten):
b. typeorm-model-generator -h localhost -d [local db name] -u [your local db user] -x [password, if applicable – otherwise do not include –x
...] -e postgres -o . -s public –ssl
i. npx typeorm-model-generator -h localhost -d local_db -u rdmtester -e postgres -o .
c. Add the entity file of the table you wish to integrate into the entity folder (ensure to include filename in the index.ts file)
2. Create a controller file (use this file to specify what info you wish to use from your table – have an idea of promises and http requests)
a. Add to controller folder
3. Create a router file (allows you to create API routes that, when called for, will execute a specified function from the controller file)
a. Then add a route to the server.ts file
4. Create a service file (will allow you to call the API – as some functions take in arguments)
5. Generate a table component (optional: for if you want to view table data on front end)
a. Run the following command shown at the beginning of the following video in the app directory:
 5.

b. https://www.youtube.com/watch?v=ao-nY-9biWs (then follow steps – I'd recommend watching the video through first before following
along)

Troubleshooting
Error: cannot find module ‘selenium-webdriver’
Use: npm install --save selenium-webdriver
Error: listen EADDRINUSE: address already in use :::8080
Refer to https://stackoverflow.com/questions/39322089/node-js-port-3000already-in-use-but-it-actually-isnt
Also make sure to exit the process from running ‘npm run server’ before running the server again

If your local grid is not working, check your Wi-Fi (do not connect to corporate Wi-Fi – if Wi-Fi isn’t working, try ethernet)
Make sure there is an entry in the test_suite database table for id=0. This is necessary because that is where the config file directs test scripts
that don’t fit into any of the predefined test suites.
If building the app is failing due to packages missing run the `npm install` command to install any other missing packages and then retry the build
and make sure the npm and node version are correct.
When running scripts, the framework must be running due to the API call made by config.py in order to find the test suite to match the script to.
When you first start the framework, you will need to create an account to access the scheduler and results component. Navigate to the profile
screen and register using your rogers email. Once you have created an account just sign in with those credentials and you should be able to
access both components.

Useful Resources
Postgres:

Command line: http://www.postgresqltutorial.com/

Python:
http://www.postgresqltutorial.com/postgresql-python/
https://pynative.com/python-postgresql-tutorial/
API: https://www.codementor.io/olawalealadeusi896/building-a-simple-api-with-nodejsexpressjs-and-postgresql-db-masuu56t7

TypeORM:

Building queries: https://github.com/typeorm/typeorm/blob/master/docs/findoptions.md

TypeScript:

Overview: https://devdocs.io/typescript/

Angular:

Data table:
https://blog.angular-university.io/angular-material-data-table/
https://appdividend.com/2018/11/07/angular-material-table-tutorialexample/#2_Install_Angular_Material_Libraries
https://stackblitz.com/angular/dnbermjydavk?file=app%2Ftable-overviewexample.ts
Material: https://alligator.io/angular/material-design-angular-reference/
Components: https://www.npmjs.com/package/typeorm-model-generator

Heroku:

Node: https://devcenter.heroku.com/articles/getting-started-with-nodejs#deploy-theapp
psql: https://devcenter.heroku.com/articles/heroku-postgresql#pg-pull
Troubleshooting: https://help.heroku.com/XOBUHLKQ/why-do-i-see-a-message-youappear-to-have-cloned-an-empty-repository-when-using-
heroku-git-clone

Selenium:

Grid: https://www.seleniumhq.org/docs/07_selenium_grid.jsp

Python:

APScheduler: https://apscheduler.readthedocs.io/en/latest/
Multiprocessing: https://medium.com/@leportella/how-to-run-parallel- processes8939dafae81e
Subprocesses: https://www.sharats.me/posts/the-ever-useful-and-neat- subprocessmodule/