org.evomaster.client.java.controller.internal

Class SutController

java.lang.Object

org.evomaster.client.java.controller.internal.SutController

All Implemented Interfaces:

SutHandler

Direct Known Subclasses:

EmbeddedSutController, ExternalSutController

public abstract class SutController
extends Object
implements SutHandler

Abstract class used to connect to the EvoMaster process, and that is responsible to start/stop/restart the tested application, ie the system under test (SUT)

Constructor Summary

Constructors

Constructor and Description
SutController()

Method Summary

Modifier and Type	Method and Description
ExtraHeuristicsDto	computeExtraHeuristics()
void	enableComputeSqlHeuristicsOrExtractExecution(boolean enableSqlHeuristics, boolean enableSqlExecution)
void	execInsertionsIntoDatabase(List<InsertionDto> insertions) Execute the given data insertions into the database (if any)
int	getActionIndex()
abstract List<AdditionalInfo>	getAdditionalInfoList()
abstract Connection	getConnection() If the system under test (SUT) uses a SQL database, we need to have a configured connection to access it.
String	getControllerHost()
int	getControllerPort()
int	getControllerServerPort()
abstract String	getDatabaseDriverName() If the system under test (SUT) uses a SQL database, we need to specify the driver used to connect, eg.
List<ExtraHeuristicsDto>	getExtraHeuristics()
abstract List<AuthenticationDto>	getInfoForAuthentication() If the application uses some sort of authentication, these details need to be provided here.
abstract String	getPackagePrefixesToCover() A "," separated list of package prefixes or class names.
abstract SutInfoDto.OutputFormat	getPreferredOutputFormat() Test cases could be outputted in different language (e.g., Java and Kotlin), using different testing libraries (e.g., JUnit 4 or 5).
abstract ProblemInfo	getProblemInfo() Depending of which kind of SUT we are dealing with (eg, REST, GraphQL or SPA frontend), there is different info that must be provided.
DbSchemaDto	getSqlDatabaseSchema() Extra information about the SQL Database Schema, if any is present.
abstract List<TargetInfo>	getTargetInfos(Collection<Integer> ids)
abstract UnitsInfoDto	getUnitsInfoDto()
protected UnitsInfoDto	getUnitsInfoDto(UnitsInfoRecorder recorder)
void	handleSql(String sql) Calculate heuristics based on intercepted SQL commands
void	initSqlHandler() This is needed only during test generation (not execution), and it is automatically called by the EM controller after the SUT is started.
abstract boolean	isInstrumentationActivated() Check if bytecode instrumentation is on.
abstract boolean	isSutRunning() Check if the system under test (SUT) is running and fully initialized
void	newAction(ActionDto dto) As some heuristics are based on which action (eg HTTP call, or click of button) in the test sequence is executed, and their order, we need to keep track of which action does cover what.
abstract void	newActionSpecificHandler(ActionDto dto)
abstract void	newSearch() Re-initialize all internal data to enable a completely new search phase which should be independent from previous ones
void	newTest() Re-initialize some internal data needed before running a new test
abstract void	newTestSpecificHandler()
void	resetExtraHeuristics()
void	setControllerHost(String controllerHost)
void	setControllerPort(int controllerPort)
abstract void	setKillSwitch(boolean b)
boolean	startTheControllerServer() Start the controller as a RESTful server.
boolean	stopTheControllerServer()
boolean	verifySqlConnection() Either there is no connection, or, if there is, then it must have P6Spy configured.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface org.evomaster.client.java.controller.SutHandler

resetStateOfSUT, setupForGeneratedTest, startSut, stopSut

Constructor Detail

SutController

public SutController()

Method Detail

startTheControllerServer

public final boolean startTheControllerServer()

Start the controller as a RESTful server. Use the setters of this class to change the default port and host.
This method is blocking until the server is initialized.

Returns:

true if there was no problem in starting the controller

stopTheControllerServer

public final boolean stopTheControllerServer()

getControllerServerPort

public final int getControllerServerPort()

Returns:

the actual port in use (eg, if it was an ephemeral 0)

getControllerPort

public final int getControllerPort()

setControllerPort

public final void setControllerPort(int controllerPort)

getControllerHost

public final String getControllerHost()

setControllerHost

public final void setControllerHost(String controllerHost)

execInsertionsIntoDatabase

public void execInsertionsIntoDatabase(List<InsertionDto> insertions)

Description copied from interface: SutHandler

Execute the given data insertions into the database (if any)

Specified by:

execInsertionsIntoDatabase in interface SutHandler

Parameters:

insertions - DTOs for each insertion to execute

getActionIndex

public int getActionIndex()

handleSql

public final void handleSql(String sql)

Calculate heuristics based on intercepted SQL commands

Parameters:

sql - command as a string

enableComputeSqlHeuristicsOrExtractExecution

public final void enableComputeSqlHeuristicsOrExtractExecution(boolean enableSqlHeuristics,
                                                               boolean enableSqlExecution)

initSqlHandler

public final void initSqlHandler()

This is needed only during test generation (not execution), and it is automatically called by the EM controller after the SUT is started.

resetExtraHeuristics

public final void resetExtraHeuristics()

getExtraHeuristics

public final List<ExtraHeuristicsDto> getExtraHeuristics()

computeExtraHeuristics

public final ExtraHeuristicsDto computeExtraHeuristics()

getSqlDatabaseSchema

public final DbSchemaDto getSqlDatabaseSchema()

Extra information about the SQL Database Schema, if any is present. Note: this is extracted by querying the database itself. So the database must be up and running.

Returns:

a DTO with the schema information

See Also:

getConnection()

verifySqlConnection

public final boolean verifySqlConnection()

Either there is no connection, or, if there is, then it must have P6Spy configured. But this might not apply to all kind controllers

Returns:

false if the verification failed

newSearch

public abstract void newSearch()

Re-initialize all internal data to enable a completely new search phase which should be independent from previous ones

newTest

public final void newTest()

Re-initialize some internal data needed before running a new test

newAction

public final void newAction(ActionDto dto)

As some heuristics are based on which action (eg HTTP call, or click of button) in the test sequence is executed, and their order, we need to keep track of which action does cover what.

Parameters:

dto - the DTO with the information about the action (eg its index in the test)

newTestSpecificHandler

public abstract void newTestSpecificHandler()

newActionSpecificHandler

public abstract void newActionSpecificHandler(ActionDto dto)

isInstrumentationActivated

public abstract boolean isInstrumentationActivated()

Check if bytecode instrumentation is on.

Returns:

true if the instrumentation is on

isSutRunning

public abstract boolean isSutRunning()

Check if the system under test (SUT) is running and fully initialized

How to implement this method depends on the library/framework used to build the application. In Spring applications, this can be done with something like: ctx != null && ctx.isRunning(), where ctx is a field where ConfigurableApplicationContext should be stored when starting the application.

Returns:

true if the SUT is running

getPackagePrefixesToCover

public abstract String getPackagePrefixesToCover()

A "," separated list of package prefixes or class names. For example, "com.foo.,com.bar.Bar". This is used to specify for which classes we want to measure code coverage.

Note: be careful of using something as general as "com." or "org.", as most likely ALL your third-party libraries would be instrumented as well, which could have a severe impact on performance.

Returns:

a String representing the packages to cover

getInfoForAuthentication

public abstract List<AuthenticationDto> getInfoForAuthentication()

If the application uses some sort of authentication, these details need to be provided here. Even if EvoMaster can have access to the database, it would not be able to recover hashed passwords.

To test the application, there is the need to provide auth for at least 1 user (and more if they have different authorization roles). When EvoMaster generates test cases, it can decide to use the credential of any user provided by this method.

What type of info to provide here depends on the auth mechanism, e.g., Basic or cookie-based (using CookieLoginDto). To simplify the creation of these DTOs with auth info, you can look at AuthUtils.

If the credential are stored in a database, be careful on how the method resetStateOfSUT is implemented. If you delete all data with DbCleaner, then you will need as well to recreate the auth details. This can be put in a script, executed then with SqlScriptRunner.

Returns:

a list of valid authentication credentials, or null if * none is necessary

getConnection

public abstract Connection getConnection()

If the system under test (SUT) uses a SQL database, we need to have a configured connection to access it.

This method is related to SutHandler.resetStateOfSUT(). When accessing a Connection object to reset the state of the application, we suggest to save it to field (eg when starting the application), and return such field here, e.g., return connection;. This connection object will be used by EvoMaster to analyze the state of the database to create better test cases.

Returns:

null if the SUT does not use any SQL database

getDatabaseDriverName

public abstract String getDatabaseDriverName()

If the system under test (SUT) uses a SQL database, we need to specify the driver used to connect, eg. org.h2.Driver. This is needed for when we intercept SQL commands with P6Spy

Returns:

null if the SUT does not use any SQL database

getTargetInfos

public abstract List<TargetInfo> getTargetInfos(Collection<Integer> ids)

getAdditionalInfoList

public abstract List<AdditionalInfo> getAdditionalInfoList()

Returns:

additional info for each action in the test. The list is ordered based on the action index.

getProblemInfo

public abstract ProblemInfo getProblemInfo()

Depending of which kind of SUT we are dealing with (eg, REST, GraphQL or SPA frontend), there is different info that must be provided. For example, in a RESTful API, you need to speficy where the OpenAPI/Swagger schema is located.

The interface ProblemInfo provides different implementations, like RestProblem. You will need to instantiate one of such classes, and return it here in this method.

Returns:

an instance of object with all the needed data for the specific addressed problem

getPreferredOutputFormat

public abstract SutInfoDto.OutputFormat getPreferredOutputFormat()

Test cases could be outputted in different language (e.g., Java and Kotlin), using different testing libraries (e.g., JUnit 4 or 5). Here, need to specify the default option.

Returns:

the format in which the test cases should be generated

getUnitsInfoDto

public abstract UnitsInfoDto getUnitsInfoDto()

setKillSwitch

public abstract void setKillSwitch(boolean b)

getUnitsInfoDto

protected UnitsInfoDto getUnitsInfoDto(UnitsInfoRecorder recorder)