3. Installing the components of Mark59

Installing Mark59 using the artefacts from mark59.com/downloads and the Samples

The instructions below assume a Windows install, and you use locations as specified. You'll need to compensate within these instructions if you have done otherwise.

For the sample Selenium projects (and DataHunter depending on how you chose to implement it) we assume you will be using the Eclipse IDE (or similar such as STS), and have downloaded the Mark59 GitHub repo at https://github.com/mark-5-9/mark59 on your machine at C:\gitrepo\mark-5-9\mark59.

An assumption is also made that your local ports 8080 and 8081 are available - you will need to review and change the ".bat" files in the appropriate places if not (should be quite straightforward).

The "download file" mentioned in these instructions refers to latest version of the mark59-{version}.zip file available at https://mark59.com/downloads/, and assume you have unzipped the file somewhere on your computer.

Prerequisite Skills

For Selenium-JMeter scripting some knowledge of Java is assumed. You should know how to code and run a simple Java program from the Eclipse IDE (or similar), and understand basic Maven and Git usage.

To just install and execute the Trend Analysis Web Tool, Trend Analysis Data Load, Enhanced JMeter Reporting and the DataHunter application, you don't need Java knowledge, but you will need to be familiar with run (.bat ) files. You should have some basic database knowledge for the MySQL install (which in theory should be simple, but be warned, can be quite frustrating if something doesn't go quite perfect).

Prerequisite Software

  • Java 8+. Mark59 is built to 1.8 compliance - we have also tested and executed on OpenJDK 11

  • Git: Your favourite Git tool (our team use GibHub Desktop, but the office geeks just run from command line)

  • Eclipse IDE (or similar such as STS). It's really up to you, nothing we have done ties into a particular IDE (or any IDE at all for that matter).

  • Maven. We just use the 'embedded' Eclipse install (3.6.1 at time of writing - and the same version number in our Jenkins builds). Our Maven builds are relatively straightforward, so any recent version should be fine.

  • JMeter. We have tested on all JMeter 5.x versions, but we recommend using the latest unless otherwise stated here (5.2.1 at time of writing). There is some incompatibility with JMeter 4 or older, so we suggest the minimum version you should use is 5.0.

  • Chrome and Chromedriver - versioning is discussed below.

  • MySQL (with MySQL Workbench) We recommend using the latest version available. We have developed on 8.x Community Edition versions - Trend Analysis uses some fairly advanced SQL, so we strongly suggest an 8.x version as a minimum.

  • Continuous Integration requirements using Jenkins will be discussed separately, and are not required for the software installs described in this section..

Selenium-JMeter Scripting

There is no install required. In order to use the Mark59 framework in a script, you need to create a Java Maven project which has this entry in its pom.

<dependency>
<groupId>com.mark59</groupId>
<artifactId>mark59-selenium-implementation</artifactId>
<version>2.2</version>
</dependency>

However, as running the samples is a relatively simple procedure, we suggest you install the sample selenium scripts if you are using mark59 for the first time. Read on...

Installing and Executing the Selenium-JMeter Sample Scripts

Here we outline the steps required to get the sample scripts up and running.

  1. Install a local copy of DataHunter

The sample scripts use DataHunter as the application under test, and so a local version of DataHunter is required. Here are a few ways of getting a local copy running:

  • Just run it from Eclipse (recommended)

    • In Eclipse, install the "Spring Tool Suite (STS) for Eclipse" plugin from the Marketplace (alternatively you could use STS). This will allow you to open a "Boot Dashboard" view.

    • Import DataHunter project from C:\gitrepo\mark-5-9\mark59 into Eclipse:

      • File -> Import -> Existing Maven Projects -> to Root Directory 'C:\gitrepo\mark-5-9\mark59' -> select dataHunter/pom.xml > Finish

    • Start DataHunter from the "Boot Dashboard".

    • URL for DataHunter home page is http://localhost:8081/dataHunter/

Starting dataHunter using the Boot Dashboad

  1. Import the following Maven projects from C:\gitrepo\mark-5-9\mark59 into Eclipse:

    1. mark59-selenium-sample-dsl

    2. dataHunterPVTest

Note there is no need to perform a Maven build in order run the scripts from Eclipse.

Project imports to run DataHunter and the Sample Scripts in Ecplise
  • Attempt to "run as Java Application" the script : com.mark59.datahunter.performanceTest.scripts.DataHunterLifecyclePvtScript

    Even if the setup is all good, it is possible you will get a failure due to a mismatch of the Selenium Chromedriver and the version of Chrome on your machine. If so, you can replace 'chromedriver.exe' in the project root with a compatible version. Further details are in Chrome Browser Setup and Download Chromedriver For Your Chrome Version.

Console output from an execution of DataHunterLifecyclePvtScript
  • (optional) Run as Java Application the script : com.mark59.datahunter.performanceTest.scripts.DataHunterLifecycleIteratorPvtScript

    Similar to running DataHunterLifecyclePvtScript, but this script demonstrates the 'iterator' class built into Mark59

  • (optional) Run as Java Application the script : com.mark59.datahunter.performanceTest.scripts.DataHunterBasicSampleScript A very simple script, so is a good way to see what the Mark59 is providing, particularly if you are not familiar with Selenium.

Executing the Selenium-JMeter Sample Scripts in JMeter

Uses the JMeter Test Plan DataHunterSeleniumTestPlan.jmx in the dataHunterPVTest project to run the sample scripts, and (optionally) obtain the local machine's server metrics.

  • Perform a Maven build on project mark59-selenium-sample-dsl using goals 'clean package install'. This will create a mark59-selenium-sample-dsl.jar file in your local Maven repository that is used by the next step.

Using Eclipse to perform the Maven build for the mark59-selenium-sample-dsl project
  • Perform a Maven build on project dataHunterPVTest project using Maven goals 'clean package'. This will create a target jar of dataHunterPVTest.jar (in the 'target' folder of the project)

  • (optional) Download mark59-server-metrics.jar from the Mark59 downloads page (it's under the mark59-server-metrics folder of the download file).

  • Install a clean version of JMeter at C:\apache-jmeter. (It can be installed under another directory name, but an install at C:\apache-jmeter is assumed in the setup for the Continuous Integration chapter).

  • copy mark59.properties and chromedriver.exe from the dataHunterPVTest project root into the JMeter /bin directory

  • copy dataHunterPVTest.jar and (optional) mark59-server-metrics.jar into the JMeter /lib/ext directory

  • start JMeter, and open test plan in the dataHunterPVTest project at C:\gitrepo\mark-5-9\mark59\dataHunterPVTest\test-plans\DataHunterSeleniumTestPlan.jmx. Note: You will need to delete the ServerUtil_localhost Thread Group if you have not copied mark59-server-metrics.jar into lib/ext.

  • Run! You can see the progress in the View Results Tree listener. Note: don't get stressed if you see some DataHunterLifeCycle results go red (failure). The transaction 'DH-lifecycle-0299-sometimes-I-fail' may of been deliberately set to randomly fail a certain percentage of the time.

Running DataHunterSeleniumTestPlan in Jmeter
  • To confirm the run has gone OK, inspect output file C:\Jmeter_Results\DataHunter\DataHunterTestResults.csv. You should see a mixture of 'labels' like 'CPU_mylocal', 'Memory_mylocal_FreeVirtualG,DataHunterLifecycle', 'DH-lifecycle-0200-addPolicy' and so on. The file should be around 300+ lines, all going well (less if you haven't captured metrics).

Typical beginning of the DataHunterTestResults.csv output file

Installing the Trend Analysis Web Application.

The Trend Analysis web application is a Spring Boot app 'metric.war'. It requires a MySQL database to run, so that has to be created first. All files are available on the downloads page in the Trend Analysis section.

MySQL database build

  • You will need to install MySQL (minimum versions 8.x)

  • During the MySQL install, the easiest thing to do is to take defaults (ie use port 3306), except at "MySQL" User Account, add User Name 'admin' password 'admin' (you can also do it later if you miss it - see MYSQLcreateAdminUser.sql in the metrics\databaseScripts folder of the download file).

  • After completing the MySQL installation, review Appendix C. MySQL Installation before continuing to the next step

  • Build the 'pvmetrics' database via the MySQL Workbench 'Data import' option using file MYSQLpvmetricsDataBaseCreation.sql. It contains sample runs for applications named 'DataHunter' and 'DataHunterDistributed'. The most recent 'DataHunter' run on the database links to sample report data embedded in the application, to give an indication of how we link to reports and CI runs. To perform the import, From the ribbon menu select > Server > Data Import > Import from Self-Contained file and select the location of 'MYSQLpvmetricsDataBaseCreation.sql' (from themetrics\databaseScripts folder on the download install file). Then select "Start Import".

Web Application install:

  • Start the application from the cmd prompt within the metrics folder of the download file, with the command: MetricsStartFromMavenTarget.bat

Trend Analysis Graphic for DataHunter with the sample data loaded

If you have a Tomcat instance available, metrics.war can be the deployed there. Unsurprisingly, the application's URL will use the Tomcat host and port.

Install and Perform a Test Execution of Trend Analysis Data Load.

The .bat file included in the download is preset to load an output file from the execution of the DataHunterSeleniumApiTestPlan JMeter Test Plan as described in the Executing the Selenium-JMeter Sample Scripts in JMeter.

  • Run a DataHunter JMeter test as per Executing the Selenium-JMeter Sample Scripts in JMeter.

  • To perform the data upload, run the following bat file from a cmd prompt, within the directory metricsRuncheck directory of the download file : LoadDataHunterTestResultsToMark59AnalysisDB.bat

Executing metricsRuncheck
Trend Analysis Graphic for DataHunter with a new test execution loaded

Install and Perform a Test Execution of Enhanced JMeter Reporting.

The enhanced JMeter reporting execution uses a bat file to process the test output and create JMeter html reports. It is preset to load the output file from the execution of the DataHunterSeleniumApiTestPlan JMeter Test Plan as described in the Executing the Selenium-JMeter Sample Scripts in JMeter.

  • Run a DataHunter JMeter test as per Executing the Selenium-JMeter Sample Scripts in JMeter.

  • Place a new vanilla copy of JMeter at C:\apache-jmeter (this copy is used only for JMeter Report generation)

  • To perform the file conversion and JMeter report generation run bat file CreateDataHunterJmeterReports.bat, which is in the resultFilesConverter folder of the downloads file.

  • Four JMeter Reports should be output to C:\Jmeter_Reports\DataHunter

(partial) output from running the CreateDataHunterJmeterReports.bat file

Installing DataHunter

The download for DataHunter can be found within the DataHunter folder on the Mark59 downloads page.

A basic local install using the default H2 database

  • To start, execute bat file: DataHunterStartFromMavenTarget.bat in the dataHunter directory of the download file.

  • URL for home page is http://localhost:8081/dataHunter/

Implementing DataHunter using a MySQL database

To hold data on a permanent basis between runs, or if you decided to use DataHunter under significant load during a test, you should connect DataHunter to MySQL instead of using in-memory H2 database.

Note only the creation of the 'datahunterdb' database will be required if you have already installed the 'pvmetrics' database for Trend Analysis:

  • If you have not done so already you will need to install MySQL (minimum versions 8.x). Review Appendix C. MySQL Installation before continuing to the next step.

  • During the MqSql install, the easiest thing to do is to take defaults (ie use port 3306), except at "MySQL" User Account, add User Name 'admin' password 'admin' (you can also do it later if you miss it - see MYSQLcreateAdminUser.sql in the dataHunterr\databaseScripts folder of the download file).

  • Build the 'datahunterdb' database using the MySql Workbench To perform the import, From the ribbon menu select > Server > Data Import > Import from Self-Contained file and select the location of 'MYSQLdatahunterDataBaseCreation.sql' (extract from dataHunterr\databaseScripts of the download file. Then select "Start Import".

Running DataHunter connected to MySQL is similar to the H2 default install, just the bat file needs to be changed :

  1. To get DataHunter to point to the MySQL database, the DataHunterStartup.bat file needs to be edited. The line :

    1. java -jar dataHunter.war --server.port=8081 --spring.profiles.active=h2 needs to be commented out (prefixed by REM ), or removed,

    2. and this line added (its actually already in the file, the REM prefix need to be removed ): java -jar dataHunter.war --mysql.server=localhost --mysql.port=3306 --server.port=8081 --spring.profiles.active=mysql

  2. To start, execute bat file DataHunterStartFromMavenTarget.bat in the DataHunter folder of the download file.

  3. URL for home page is http://localhost:8081/dataHunter/

If you have a Tomcat instance available, dataHunter.war can be the deployed there. As already mentioned for metrics.war, the application URL will use the Tomcat host and port. In order to connect to a MySQL database, you will need to change the application.properties configuration file (tospring.profiles.active=mysql) and possibly application-mysql.properties within dataHunter. We suggest the simplest solution is to build the war from the GitHub dataHunter project source (please review the next chapter).