Package ghidra.test

Class TestEnv

  • public class TestEnv
extends java.lang.Object

    • 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() or launchDefaultTool(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() or launchDefaultTool(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.
        use instead AbstractDockingTest.waitForDialogComponent(Class)
        Waits for the first window of the given class. This method is the same as waitForDialogComponent(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 desires
        maxTimeMS - 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

      • createDefaultTool

        public PluginTool createDefaultTool()
        This method differs from launchDefaultTool() in that this method does not set the tool variable in of this TestEnv 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)

      • 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

      • getProject

        public Project getProject()

      • launchAnotherDefaultTool

        public PluginTool launchAnotherDefaultTool()
        Launches another default tool, not overwriting this env's current tool.
        Returns:
        the new tool

      • getGhidraCreatedTools

        public Tool[] 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

      • 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 name
        program - program object
        replace - if true any existing cached database with the same name will be replaced
        monitor - 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 launch
        domainFile - 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 the FrontEndTool 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)

      • 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()