2. The Mark59 GitHub Projects and Artefacts

How the Mark59 GitHub projects fit into the components of Mark59

Mark59 is structured on GitHub as a set of Maven projects. These projects are used within the components of Mark59 either as:

  • the source code used to build an executable jar (batch) or war (web application), or

  • to provide a sample of how to best use one or more components (but not part of a component itself).

A Rough Guide to the Mark59 components and their related GitHib projects

In this this section we summarise what each component does and the relationship between projects: there are subtleties not indicated on the cross above.

For the GitHub projects which build .war or .jar artefacts that are in integral part of the Mark59 framework (not just a sample project), and are not available on Maven Central, an install is available on the Mark59 downloads page. The projects are dataHunter, mark59-server-metrics, metrics, metricsRuncheck and resultFilesConverter. All projects can also can also be built from source. See the next two chapters for the details

DataHunter

DataHunter is a simple stand-alone Java Spring Boot Web application (it can also be deployed to Tomcat).

The DataHunter application is tailored to assist with retaining application-related test data during and between performance tests. If you are familiar with LoadRunner, it is akin to the Web version of VTS.

By default, the install and/or build are self-contained, and use a H2 database. The H2 database is dynamically built during the install, making it a good for choice when using DataHunter as a test-and-learn application. It can also use MySQL, which would probably be necessary if you intend to use it heavily during a performance test, or to hold data between tests.

DataHunter is used a the sample application in Mark59. Therefore the sample Selenium project dataHunterPVTest test scripts require DataHunter to be installed. Also, the supplied sample data used during the install the Trend Analysis 'metrics' project is based on DataHunter runs (it does not need DataHunter to be installed).

Summary of DataHunter related projects

Project

Required?

Artefact

Notes

DataHunter

Yes

dataHunter.war

Uses a H2 (default) or MySQL database.

dataHunterPVTest

No

dataHunterPVTest.jar

Sample Selenium project using dataHunter as the application under test.

mark59-selenium-implementation

No

mark59-selenium-implementation.jar

Only if building the dataHunterPVTest sample Selenium project. Accessed via Maven Central

mark59-core

No

mark59-core.jar

Only if building the dataHunterPVTest sample Selenium project. Accessed via Maven Central

mark59-selenium-sample-dsl

No

mark59-selenium-sample-dsl.{version.}jar

Only if building the dataHunterPVTest sample Selenium project

mark59-server-metrics

No

mark59-server-metrics.jar

Only if running the Sample JMeter test in the dataHunterPVTest project

metrics

No

metrics.war

Initial database load contains dataHunter related test results.

Selenium-JMeter Scripts

Overview

There is no 'Mark59' install required in order to build and execute Mark59 Selenium Java scripts. Once a script is written and tested, typically in Eclipse, the only build actually required is a Maven build on the project containing the script(s), which will create a jar file that needs to be copied into the 'lib/ext' directory of the JMeter instance running the test. This is because all the necessary Mark59 dependencies are accessed via Maven from the Central Repository. The Maven entry needed is:

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

It's worth noting that most of the time a single project jar containing all its necessary dependencies can be created, but there are situations where script dependencies cannot all be 'jar'ed up together, in which case a separate library of dependency jars needs to be created and copied across to JMeter. This is documented more fully in the plugins segment of the pom.xml file for the dataHunterPVTest project.

Which brings us to the sample applications. The dataHunterPVTest project contains sample Mark59 Selenium scripts, which give good coverage of the functionality available. They need a DataHunter application instance available in order to run.

The Selenium DSL (Domain-Specific Language - a term coined by Martin Fowler while working at ThoughtWorks) used in the dataHunterPVTest project is referenced from the mark59-selenium-sample-dsl sample project. It's gives a good starting point for your Selenium scripting, but may need to be extended depending on html or JavaScript structures used by the application you are testing. For this reason, it's probably better just to copy the DSL packages (com.mark59.seleniumDSL..) from mark59-selenium-sample-dsl into your own project, and consider them a starting point.

Script results output - relationship to the "Reporting and Trend Analysis" component

The results file structure of a JMeter test running a Mark59 enabled script or scripts need to be understood to get an idea of why the "Reporting and Trend Analysis" component works the way it does. By the way, nothing in the "Reporting and Trend Analysis" component requires that anything in a JMeter test needs to use or have any awareness of the Mark59 framework in order to produce a JMeter report, or even to load results into the Trend Analysis web application. The Mark59 "Reporting and Trend Analysis" components are designed to produce improved output when using Mark59 enabled scripts and components (like server metrics).

A big difference between output from a Mark59 enabled script and standard JMeter output is that sub-results have been implemented. Typically, the results output file from a JMeter test has a 'flat' structure:

transactiona, time1, elapsedtime1 transactionb, time2, elapsedtime2 transactiona, time3, elapsedtime3

With a Mark59 enabled script, many transactions cay be recorded during the execution of a single script. A summary transaction for a script run is also output , so the results have a structure:

DataHunterScript_A, time1, totalelapsedtimeofthisrunofscriptA DataHunterScript_A_transactiona, time2, elapsedtimeforScriptAtransactiona DataHunterScript_A_transactionb, time3, elapsedtimeforScriptAtransactionb DataHunterScript_B, time4, totalelapsedtimeofthisrunofscriptB DataHunterScript_B_transactiona, time5, elapsedtimeforScriptBtransactiona DataHunterScript_B_transactionb, time6, elapsedtimeforScriptBtransactionb DataHunterScript_B_transactionc, time7, elapsedtimeforScriptBtransactionb DataHunterScript_A, time8, totalelapsedtimeofthisrunofscriptA DataHunterScript_A_transactiona, time9, elapsedtimeforScriptAtransactiona DataHunterScript_A_transactionb, time10,elapsedtimeforScriptAtransactionb

The JMeter output file can be formatted as XML or CSV, and the actual way this structure is implemented differs in each, but they both conceptually contain this two-level structure.

In order to produce a nice JMeter report that understands this structure the resultFilesConverter project artefact can be used. If you don't, you can still get a report, it's just that it will always blurt out all these transactions as if it was dealing with a flat structure, which is usually not what you want.

Summary of Selenium-JMeter related projects

Project

Required?

Artefact

Notes

mark59-selenium-implementation

Yes

mark59-selenium-implementation.jar

Accessed via Maven Central

mark59-core

Yes

mark59-core.jar

In the dependency tree of mark59-selenium-implementation, so automatically included via Maven

dataHunterPVTest

No

dataHunterPVTest.jar

Sample Selenium project using dataHunter as the application under test.

mark59-selenium-sample-dsl

No

mark59-selenium-sample-dsl.{version.}jar

Only if building the dataHunterPVTest Sample Selenium project

mark59-server-metrics

No

mark59-server-metrics.jar

Only if running the Sample JMeter test in the dataHunterPVTest project

resultFilesConverter

No

resultFilesConverter.jar

To help generate 'nicely' formatted JMeter report(s) when Mark59 enabled script(s) are used.

Trend Analysis and Reporting

The Mark59 Reporting and Trends Analysis Component deals with performance test output. There are two sub-components, that can be built or installed independently, and so are discussed separately.

Trend Analysis

Uses a Spring Boot executable metricsRuncheck.jar to load JMeter test results file data into a MySQL database used by the Trend Analysis tool, which is a Spring Boot Web Application metrics.war(it can also be deployed to Tomcat).

The 'metricsRuncheck' project uses code from 'metrics', but otherwise these two projects have no dependencies on other Mark59 projects, other than the fact, not shown in the table below, that 'metricsRuncheck' especially caters for output from Mark59 enabled scripts.

Summary of Trend Analysis related projects

Project

Required?

Artefact

Notes

metrics

Yes

metrics.war

Requires a MySQL database 'pvmetrics'

metricsRuncheck

Yes

metricsRuncheck.jar

Requires a MySQL database 'pvmetrics'

Reporting - Enhanced JMeter Reporting

Uses a Java executable resultFilesConverter.jar . Its input is the JMeter test results file created by a test run, and it outputs JMeter test results file or files that cater for Mark59 enabled script output. The reasoning behind the need for enhanced reporting has been discussed above, although not options are covered there. The 'resutlsFileConverter' can split a JMeter results file into multiple result files by type of data (transactional, CPU, Memory, Datapoint). Other parameters can be selected which affect output as well. The resulting output file or files can then be fed into the standard JMeter report generation command.

The 'resultFilesConverter' program is in some ways quite similar to the 'metricsRuncheck.jar' Trend Analysis load program. Both have to process the same JMeter results output file, and so need to be able to interpret Mark59 enabled script output. Its the output requirements that differ. To keep the "Reporting" and "Trend Analysis" functions independent of each other, it was decided to keep these two programs separate. Also, 'resultFilesConverter' boils down to being a relatively simple utility program, so the duplication of logic isn't onerous.

The 'resultFilesConverter ' project is completely standalone, and has no relationship or dependencies on the other Mark59, other than the fact, not shown in the table below, that it especially caters for output from Mark59 enabled scripts.

Summary of Enhanced JMeter Reporting related projects

Project

Required?

Artefact

Notes

resultFilesConverter

Yes

resultFilesConverter.jar

standalone

mark59-server-metrics and the mark59-core projects

Build and project dependencies

The 'mark59-server-metrics' project is a bit of an odd one out in our project structure. After some debate it was decided to include the project it in the Mark59 framework, as we think it may serve other teams in the same way it has served us at times. It provides only basic, raw metric data, but has the substantial advantage that it is an "agentless monitoring" solution (as opposed to JMeter PerfMon for example).

Another reason for the inclusion of mark59-server-metrics is that is an example of how the mark59-core project can be used for something other than the Selenium implementation. You can review ServerMetricsCapture.java and NewRelicServerMetricsCapture.java in the project to get the idea.

The mark59-server-metrics project has no other relationship or dependencies on Mark59 projects, other than an its usage in the JMeter test plan for the dataHunterPVTest sample project (not shown in the table below) .

Summary of mark59-server-metrics related projects

Project

Required?

Artefact

Notes

mark59-server-metrics

Yes

mark59-server-metrics.jar

Simple Win/Unix/Linux/New Relic agent-less metrics monitoring

mark59-core

Yes

mark59-core.jar

In the project pom.xml for mark59-server-metrics, so automatically included via Maven