Class TestEnv
- java.lang.Object
-
- ghidra.test.TestEnv
-
public class TestEnv extends java.lang.Object
-
-
Constructor Summary
Constructors Modifier Constructor Description TestEnv()
Constructor for Ghidra A new test project is established.TestEnv(long abortTimeout, java.lang.String projectName)
Constructor for Ghidra A new test project is established using the specified projectName.protected
TestEnv(GhidraProject project)
This constructor allows clients to manage their own projects.TestEnv(java.lang.String projectName)
Constructor for Ghidra A new test project is established using the specified projectName.
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods Modifier and Type Method Description <T extends Plugin>
TaddPlugin(java.lang.Class<T> c)
Adds and returns the plugin to this env's tool for the given class.void
close(Program p)
Closes the given program, ignoring all changes, for each tool known to this TestEnv.void
closeAndReopenProject()
A convenience method to close and then reopen the default project created by this TestEnv instance.void
closeTool()
Closes the TestEnv's default tool.void
closeTool(PluginTool toolToClose)
Closes the given tool.void
closeTool(PluginTool toolToClose, boolean ignoreChanges)
ToolConnection
connectTools(PluginTool producer, PluginTool consumer)
PluginTool
createDefaultTool()
This method differs fromlaunchDefaultTool()
in that this method does not set thetool
variable in of thisTestEnv
instance.void
disconnectTools(PluginTool producer, PluginTool consumer)
void
dispose()
protected void
disposeFrontEndTool()
static ResourceFile
findProvidedDataTypeArchive(java.lang.String relativePathName)
ComponentProvider
getFrontEndProvider()
FrontEndTool
getFrontEndTool()
PluginTool[]
getGhidraCreatedTools()
Returns an array of tools spawned by the Ghidra environment.GhidraProject
getGhidraProject()
Returns GhidraProject associated with this environment<T extends Plugin>
TgetPlugin(java.lang.Class<T> c)
ProgramDB
getProgram(java.lang.String programName)
Open a read-only test program from the test data directory.Project
getProject()
ProjectManager
getProjectManager()
PluginTool
getTool()
Get the tool associated with this test environment.boolean
isProgramCached(java.lang.String programName)
Determine if specified program already exists with the program cachePluginTool
launchAnotherDefaultTool()
Launches another default tool, not overwriting this env's current tool.PluginTool
launchDefaultTool()
Launches the default tool of the test system ("CodeBrowser").PluginTool
launchDefaultTool(Program program)
Launches the default tool of the test system ("CodeBrowser") using the given program.protected PluginTool
launchDefaultToolByName(java.lang.String toolName)
PluginTool
launchTool(java.lang.String toolName)
Launches a tool of the given name using the given domain file.PluginTool
launchTool(java.lang.String toolName, DomainFile domainFile)
Launches a tool of the given name using the given domain file.ProgramDB
loadAnalyzedNotepad()
Program
loadResourceProgramAsBinary(java.lang.String programName, Language language, CompilerSpec compilerSpec)
Program
loadResourceProgramAsBinary(java.lang.String programName, Processor processor)
void
open(Program program)
Opens the given program in the test tool.protected void
printProgramConsumers(Program program)
void
release(Program program)
Release a program which was obtained from this test environment.void
removeFromProgramCache(java.lang.String programName)
Remove specified program from cachevoid
resetDefaultTools()
PluginTool
restartTool()
DomainFile
restoreDataTypeArchive(java.lang.String relativePathName, DomainFolder domainFolder)
Creates a project data type archive in the indicated test project folder from the ".gdt" file indicated by the relative pathname.DomainFile
restoreProgram(java.lang.String programName)
Copies the specified program zip file to the JUnit test project's root folder.ScriptTaskListener
runScript(java.io.File scriptFile)
void
saveRestoreToolState()
void
saveToCache(java.lang.String progName, ProgramDB program, boolean replace, TaskMonitor monitor)
Save a program to the cached program store.void
setAutoSaveEnabled(boolean enabled)
Sets the auto-save feature for all tool instances running under theFrontEndTool
created by this TestEnv instance.protected void
setAutoSaveEnabled(FrontEndTool frontEndToolInstance, boolean enabled)
FrontEndTool
showFrontEndTool()
PluginTool
showTool()
Shows any previously created tool, creating a simple empty tool if not tool has yet been created.PluginTool
showTool(Program p)
Shows any previously created tool, creating a simple empty tool if not tool has yet been created.<T extends DialogComponentProvider>
TwaitForDialogComponent(java.lang.Class<T> ghidraClass, int maxTimeMS)
Deprecated.java.awt.Window
waitForWindow(java.lang.String title, int timeoutMS)
Deprecated.
-
-
-
Constructor Detail
-
TestEnv
public TestEnv() throws java.io.IOException
Constructor for Ghidra A new test project is established. If it already exists it will first be deleted.- Throws:
java.io.IOException
- if there is an issue creating a test project
-
TestEnv
public TestEnv(java.lang.String projectName) throws java.io.IOException
Constructor for Ghidra A new test project is established using the specified projectName. If it already exists it will first be deleted. If the test environment is not disposed within 1 minute the tests iwll be aborted- Parameters:
projectName
- the name of the project- Throws:
java.io.IOException
- if there is an issue creating a test project
-
TestEnv
public TestEnv(long abortTimeout, java.lang.String projectName) throws java.io.IOException
Constructor for Ghidra A new test project is established using the specified projectName. If it already exists it will first be deleted.- Parameters:
abortTimeout
- number of minutes within which this test environment must be disposed. If not disposed in a timely manner, System.exit will be invoked.projectName
- the name of the project- Throws:
java.io.IOException
- if there is an issue creating a test project
-
TestEnv
protected TestEnv(GhidraProject project)
This constructor allows clients to manage their own projects. Also, this constructor will not enforce having only a single env instance running, which allows for multi-project testing. All other constructors will enforce that a single instance of TestEnv can be running at one time, closing any previously opened instances before finishing construction.Note: this constructor is meant for subclasses.
- Parameters:
project
- the initialized project
-
-
Method Detail
-
getTool
public PluginTool getTool()
Get the tool associated with this test environment.- Returns:
- the default test tool for this environment
-
closeTool
public void closeTool()
Closes the TestEnv's default tool. This method is asynchronous, so you must wait for the Swing thread to perform the work yourself. Watch out for modal dialogs.
-
closeTool
public void closeTool(PluginTool toolToClose)
Closes the given tool. This method is asynchronous, so you must wait for the Swing thread to perform the work yourself. Watch out for modal dialogs.- Parameters:
toolToClose
- The tool to close.
-
closeTool
public void closeTool(PluginTool toolToClose, boolean ignoreChanges)
-
disposeFrontEndTool
protected void disposeFrontEndTool()
-
saveRestoreToolState
public void saveRestoreToolState()
-
getPlugin
public <T extends Plugin> T getPlugin(java.lang.Class<T> c)
-
addPlugin
public <T extends Plugin> T addPlugin(java.lang.Class<T> c) throws PluginException
Adds and returns the plugin to this env's tool for the given class.If you have not created a tool using this env, then the default tool from
lazyTool()
is used. If you have launched a tool, then that tool is used. In the following example, the given plugin is added to the default tool:TestEnv env = new TestEnv(); env.launchDefaultTool(); FooPlugin foo = env.addPlugin(FooPlugin.class);
- Parameters:
c
- the plugin class- Returns:
- the plugin instance
- Throws:
PluginException
- if there is an exception adding the given tool
-
showTool
public PluginTool showTool()
Shows any previously created tool, creating a simple empty tool if not tool has yet been created.This method is considered sub-standard and users should prefer instead
launchDefaultTool()
orlaunchDefaultTool(Program)
.- Returns:
- the newly shown tool
-
showTool
public PluginTool showTool(Program p)
Shows any previously created tool, creating a simple empty tool if not tool has yet been created. The given program will be opened in the tool.This method is considered sub-standard and users should prefer instead
launchDefaultTool()
orlaunchDefaultTool(Program)
.- Parameters:
p
- the program- Returns:
- the newly shown tool
-
waitForWindow
@Deprecated public java.awt.Window waitForWindow(java.lang.String title, int timeoutMS)
Deprecated.
-
waitForDialogComponent
@Deprecated public <T extends DialogComponentProvider> T waitForDialogComponent(java.lang.Class<T> ghidraClass, int maxTimeMS)
Deprecated.Waits for the first window of the given class. This method is the same aswaitForDialogComponent(Class, int)
with the exception that the parent window is assumed to be this instance's tool frame.- Parameters:
ghidraClass
- The class of the dialog the user desiresmaxTimeMS
- The max amount of time in milliseconds to wait for the requested dialog to appear.- Returns:
- The first occurrence of a dialog that extends the given
ghirdraClass
-
getFrontEndTool
public FrontEndTool getFrontEndTool()
-
getFrontEndProvider
public ComponentProvider getFrontEndProvider()
-
showFrontEndTool
public FrontEndTool showFrontEndTool()
-
createDefaultTool
public PluginTool createDefaultTool()
This method differs fromlaunchDefaultTool()
in that this method does not set thetool
variable in of thisTestEnv
instance.- Returns:
- the tool
-
launchDefaultTool
public PluginTool launchDefaultTool()
Launches the default tool of the test system ("CodeBrowser"). This method will load the tool from resources and not from the user's Ghidra settings.Note: Calling this method also changes the tool that this instance of the TestEnv is using, which is the reason for the existence of this method.
- Returns:
- the tool that is launched
-
launchDefaultToolByName
protected PluginTool launchDefaultToolByName(java.lang.String toolName)
-
runScript
public ScriptTaskListener runScript(java.io.File scriptFile) throws PluginException
- Throws:
PluginException
-
getGhidraProject
public GhidraProject getGhidraProject()
Returns GhidraProject associated with this environment- Returns:
- the project
-
closeAndReopenProject
public void closeAndReopenProject() throws java.io.IOException
A convenience method to close and then reopen the default project created by this TestEnv instance. This will not delete the project between opening and closing and will restore the project to its previous state.- Throws:
java.io.IOException
- if any exception occurs while saving and reopening
-
getProjectManager
public ProjectManager getProjectManager()
-
getProject
public Project getProject()
-
restartTool
public PluginTool restartTool()
-
launchAnotherDefaultTool
public PluginTool launchAnotherDefaultTool()
Launches another default tool, not overwriting this env's current tool.- Returns:
- the new tool
-
getGhidraCreatedTools
public PluginTool[] getGhidraCreatedTools()
Returns an array of tools spawned by the Ghidra environment. NOTE: This array will not contain any of the TestTools!- Returns:
- an array of tools spawned by the Ghidra environment
-
connectTools
public ToolConnection connectTools(PluginTool producer, PluginTool consumer)
-
disconnectTools
public void disconnectTools(PluginTool producer, PluginTool consumer)
-
restoreProgram
public DomainFile restoreProgram(java.lang.String programName) throws java.io.FileNotFoundException
Copies the specified program zip file to the JUnit test project's root folder. This means that the program will appear in the FrontEndTool as part of the project. That is the only reason to use this method vice openProgram().- Parameters:
programName
- the name of the program zip file without the ".gzf" extension.- Returns:
- the restored domain file
- Throws:
java.io.FileNotFoundException
- if the program file cannot be found
-
findProvidedDataTypeArchive
public static ResourceFile findProvidedDataTypeArchive(java.lang.String relativePathName)
-
restoreDataTypeArchive
public DomainFile restoreDataTypeArchive(java.lang.String relativePathName, DomainFolder domainFolder) throws java.lang.Exception
Creates a project data type archive in the indicated test project folder from the ".gdt" file indicated by the relative pathname.- Parameters:
relativePathName
- This should be a pathname relative to the "test_resources/testdata" director or relative to the "typeinfo" directory. The name should include the ".gdt" suffix.domainFolder
- the folder in the test project where the archive should be created- Returns:
- the domain file that was created in the project
- Throws:
java.lang.Exception
- if an exception occurs
-
saveToCache
public void saveToCache(java.lang.String progName, ProgramDB program, boolean replace, TaskMonitor monitor) throws java.lang.Exception
Save a program to the cached program store. A SaveAs will be performed on the program to its cached storage location.- Parameters:
progName
- program nameprogram
- program objectreplace
- if true any existing cached database with the same name will be replacedmonitor
- task monitor- Throws:
java.lang.Exception
- if already cached
-
isProgramCached
public boolean isProgramCached(java.lang.String programName)
Determine if specified program already exists with the program cache- Parameters:
programName
- the name- Returns:
- true if specified program already exists with the program cache
-
removeFromProgramCache
public void removeFromProgramCache(java.lang.String programName)
Remove specified program from cache- Parameters:
programName
- the name
-
loadAnalyzedNotepad
public ProgramDB loadAnalyzedNotepad()
-
getProgram
public ProgramDB getProgram(java.lang.String programName)
Open a read-only test program from the test data directory. This program must be released prior to disposing this test environment. NOTE: Some tests rely on this method returning null when file does not yet exist within the resource area (e.g., test binaries for P-Code Tests)- Parameters:
programName
- name of program database within the test data directory.- Returns:
- program or null if program file not found
-
launchDefaultTool
public PluginTool launchDefaultTool(Program program)
Launches the default tool of the test system ("CodeBrowser") using the given program. This method will load the tool from resources and not from the user's Ghidra settings.Note: Calling this method also changes the tool that this instance of the TestEnv is using, which is the reason for the existence of this method.
- Parameters:
program
- The program to load into the default tool; may be null- Returns:
- the tool that is launched
-
launchTool
public PluginTool launchTool(java.lang.String toolName)
Launches a tool of the given name using the given domain file.Note: the tool returned will have auto save disabled by default.
- Parameters:
toolName
- the tool's name- Returns:
- the tool that is launched
-
launchTool
public PluginTool launchTool(java.lang.String toolName, DomainFile domainFile)
Launches a tool of the given name using the given domain file.Note: the tool returned will have auto save disabled by default.
- Parameters:
toolName
- the name of the tool to launchdomainFile
- The domain file used to launch the tool; may be null- Returns:
- the tool that is launched
-
setAutoSaveEnabled
public void setAutoSaveEnabled(boolean enabled)
Sets the auto-save feature for all tool instances running under theFrontEndTool
created by this TestEnv instance. Auto-save is off by default when testing.- Parameters:
enabled
- true enables auto-save
-
setAutoSaveEnabled
protected void setAutoSaveEnabled(FrontEndTool frontEndToolInstance, boolean enabled)
-
loadResourceProgramAsBinary
public Program loadResourceProgramAsBinary(java.lang.String programName, Language language, CompilerSpec compilerSpec) throws LanguageNotFoundException, java.io.IOException, CancelledException, DuplicateNameException, InvalidNameException, VersionException
- Throws:
LanguageNotFoundException
java.io.IOException
CancelledException
DuplicateNameException
InvalidNameException
VersionException
-
loadResourceProgramAsBinary
public Program loadResourceProgramAsBinary(java.lang.String programName, Processor processor) throws CancelledException, DuplicateNameException, InvalidNameException, VersionException, java.io.IOException
- Throws:
CancelledException
DuplicateNameException
InvalidNameException
VersionException
java.io.IOException
-
release
public void release(Program program)
Release a program which was obtained from this test environment.- Parameters:
program
- the program
-
open
public void open(Program program)
Opens the given program in the test tool.- Parameters:
program
- the program to open
-
close
public void close(Program p)
Closes the given program, ignoring all changes, for each tool known to this TestEnv.- Parameters:
p
- the program to close
-
dispose
public void dispose()
-
printProgramConsumers
protected void printProgramConsumers(Program program)
-
resetDefaultTools
public void resetDefaultTools()
-
-