Package com.xceptance.xlt.api.engine

Class Session

  • public abstract class Session
extends java.lang.Object
    The Session object is the runtime context during one run of a certain test case.

    Multiple threads running the same test case will get different sessions. A session is the anchor that holds the data recorded during that very test run.

    ATTENTION: A session can be reused across different test runs if and only if it is cleared before its reuse.

    • Constructor Summary

      Constructors 
      Constructor Description
      Session()  

    • Method Summary

      All Methods Static Methods Instance Methods Abstract Methods Concrete Methods Deprecated Methods 
      Modifier and Type Method Description
      abstract void addShutdownListener​(SessionShutdownListener listener)
      Registers the passed shutdown listener to be called on session termination.
      abstract void clear()
      Clears the session.
      abstract int getAbsoluteUserNumber()
      Returns the number of the currently running test user.
      abstract java.lang.String getAgentID()
      Returns the ID of the current agent.
      abstract int getAgentNumber()
      Returns the number (or index) of the current agent.
      static Session getCurrent()
      Returns the thread-specific Session instance.
      abstract java.lang.String getCurrentActionName()
      Returns the name of the current action as specified when the action was started.
      abstract DataManager getDataManager()
      Returns the session's data manager.
      abstract java.lang.String getID()
      Returns the session's ID.
      abstract NetworkDataManager getNetworkDataManager()
      Returns the network data manager.
      abstract java.nio.file.Path getResultsDirectory()
      Returns the session's results directory.
      abstract java.lang.String getTestCaseClassName()
      Returns the fully qualified class name of the test case to which this session belongs.
      abstract int getTotalAgentCount()
      Returns the total count of agents that take part in a load test.
      abstract int getTotalUserCount()
      Returns the total count of test users running during a test.
      abstract int getUserCount()
      Returns the total count of the test users with the same type as the current user, for example "35".
      abstract java.lang.String getUserID()
      Returns the ID of the currently running test user, for example "TAddToCart-27".
      abstract java.lang.String getUserName()
      Returns the name of the currently running test user, for example "TAddToCart".
      abstract int getUserNumber()
      Returns the instance number of the currently running test user, for example "27".
      abstract java.util.Map<java.lang.String,​java.lang.Object> getValueLog()
      Returns this session's value log, a storage for session-specific test parameters and result data.
      abstract java.lang.String getWebDriverActionName()
      Deprecated.
      As of XLT 4.6.0, use getCurrentActionName() instead.
      abstract boolean hasFailed()
      Returns the session's failure status.
      abstract boolean isLoadTest()
      Indicates whether the current test session is executed in the context of a functional test or a load test.
      static void logEvent​(java.lang.String eventName, java.lang.String eventMessage)
      Logs an event.
      abstract void removeShutdownListener​(SessionShutdownListener listener)
      Unregisters the passed shutdown listener.
      abstract void setFailed()
      Sets the session's failure status to failed.
      abstract void setFailed​(boolean value)
      Sets the session's failure status.
      abstract void setID​(java.lang.String id)
      Sets the session's ID.
      abstract void setNotFailed()
      Unsets the session failure state.
      abstract void setWebDriverActionName​(java.lang.String webDriverActionName)
      Deprecated.
      As of XLT 4.6.0, use startAction(String) instead.
      abstract void startAction​(java.lang.String actionName)
      Tells the framework to start a new action with the given name.
      abstract void stopAction()
      Tells the framework to finish the current action.

      • Methods inherited from class java.lang.Object

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

    • Constructor Detail

      • Session

        public Session()

    • Method Detail

      • getCurrent

        public static Session getCurrent()
        Returns the thread-specific Session instance. If no such instance exists yet, it will be created.
        Returns:
        the Session instance for the current thread

      • logEvent

        public static final void logEvent​(java.lang.String eventName,
                                  java.lang.String eventMessage)
        Logs an event.
        Parameters:
        eventName - name of the event
        eventMessage - the event message

      • addShutdownListener

        public abstract void addShutdownListener​(SessionShutdownListener listener)
        Registers the passed shutdown listener to be called on session termination.
        Parameters:
        listener - the shutdown listener

      • clear

        public abstract void clear()
        Clears the session. All state is removed. This includes the request history as well.

      • getAbsoluteUserNumber

        public abstract int getAbsoluteUserNumber()
        Returns the number of the currently running test user. This value ranges from 0...(n-1), where n denotes the total number of configured test users, independent of their respective user type.
        Returns:
        the test user's absolute instance number

      • getAgentID

        public abstract java.lang.String getAgentID()
        Returns the ID of the current agent.
        Returns:
        the agent's ID

      • getAgentNumber

        public abstract int getAgentNumber()
        Returns the number (or index) of the current agent. This value ranges from 0...(n-1), where n denotes the total number of configured agents.
        Returns:
        the agent's instance number

      • getID

        public abstract java.lang.String getID()
        Returns the session's ID.
        Returns:
        the session ID

      • getTestCaseClassName

        public abstract java.lang.String getTestCaseClassName()
        Returns the fully qualified class name of the test case to which this session belongs.
        Returns:
        the test class name
        Since:
        7.0.0

      • getDataManager

        public abstract DataManager getDataManager()
        Returns the session's data manager.
        Returns:
        the data manager

      • getTotalAgentCount

        public abstract int getTotalAgentCount()
        Returns the total count of agents that take part in a load test.
        Returns:
        the total count

      • getTotalUserCount

        public abstract int getTotalUserCount()
        Returns the total count of test users running during a test. This includes all users of all types.
        Returns:
        the total count of users

      • getUserCount

        public abstract int getUserCount()
        Returns the total count of the test users with the same type as the current user, for example "35".
        Returns:
        the total count

      • getUserID

        public abstract java.lang.String getUserID()
        Returns the ID of the currently running test user, for example "TAddToCart-27".
        Returns:
        the test user's ID

      • getUserName

        public abstract java.lang.String getUserName()
        Returns the name of the currently running test user, for example "TAddToCart".
        Returns:
        the test user's name

      • getUserNumber

        public abstract int getUserNumber()
        Returns the instance number of the currently running test user, for example "27". This value ranges from 0...(n-1), where n denotes the total number of configured test users with the same type as the current test user.
        Returns:
        the test user's instance number

      • hasFailed

        public abstract boolean hasFailed()
        Returns the session's failure status.
        Returns:
        whether or not the session has failed

      • isLoadTest

        public abstract boolean isLoadTest()
        Indicates whether the current test session is executed in the context of a functional test or a load test.
        Returns:
        true if we are in the middle of a load test, false otherwise

      • getResultsDirectory

        public abstract java.nio.file.Path getResultsDirectory()
        Returns the session's results directory.
        Returns:
        the result directory

      • removeShutdownListener

        public abstract void removeShutdownListener​(SessionShutdownListener listener)
        Unregisters the passed shutdown listener.
        Parameters:
        listener - the shutdown listener

      • setFailed

        public abstract void setFailed​(boolean value)
        Sets the session's failure status.
        Parameters:
        value - whether or not the session has failed

      • setFailed

        public abstract void setFailed()
        Sets the session's failure status to failed.

      • setNotFailed

        public abstract void setNotFailed()
        Unsets the session failure state.

      • setID

        public abstract void setID​(java.lang.String id)
        Sets the session's ID.
        Parameters:
        id - the new session ID

      • getNetworkDataManager

        public abstract NetworkDataManager getNetworkDataManager()
        Returns the network data manager.
        Returns:
        network data manager

      • getWebDriverActionName

        @Deprecated
public abstract java.lang.String getWebDriverActionName()
        Deprecated.
        As of XLT 4.6.0, use getCurrentActionName() instead.

      • setWebDriverActionName

        @Deprecated
public abstract void setWebDriverActionName​(java.lang.String webDriverActionName)
        Deprecated.
        As of XLT 4.6.0, use startAction(String) instead.

      • startAction

        public abstract void startAction​(java.lang.String actionName)
        Tells the framework to start a new action with the given name. If there is still a pending (i.e. unfinished) action, then this action will be finished before the new action is started.

        Note that calling this method is not necessary for test cases that automatically manage the action life cycle. This includes test cases that are built with action classes, but also interpreted or exported script test cases. You would need to call this method for plain WebDriver-based or plain HtmlUnit-based test cases, though.

        Parameters:
        actionName - the name of the new action
        See Also:
        stopAction(), AbstractAction

      • stopAction

        public abstract void stopAction()
        Tells the framework to finish the current action. If there is no pending action, calling this method has no effect.

        Finishing an action includes logging the action's run time and result. Whether the action is logged as successful or failed depends on the session's failed state.

        See Also:
        setFailed(boolean), startAction(String)

      • getCurrentActionName

        public abstract java.lang.String getCurrentActionName()
        Returns the name of the current action as specified when the action was started. When called between two actions (i.e. after finishing the previous action, but before starting a new one), the returned action name will be null.
        Returns:
        the name of the current action, or null if there is none
        See Also:
        startAction(String)

      • getValueLog

        public abstract java.util.Map<java.lang.String,​java.lang.Object> getValueLog()
        Returns this session's value log, a storage for session-specific test parameters and result data. Any value you add to this log will later be available in the result browser. Note that the log will be cleared with each new iteration.

        This feature is intended to aid in error analysis. The data in the result browser may help you to reconstruct and rerun a failed test case iteration without having to dig into log files. Simply add any value of special interest and you will have it at hand in the result browser. This is especially useful if your test case uses random or randomly chosen test parameters.

        Data is stored as name/value pairs. Even though the log accepts any Object as the value, the value will later be converted to a string using Object.toString() for proper display in the result browser. So make sure your value classes implement this method appropriately.

        Returns:
        the values keyed by their names