class Arachni::Page::DOM::Transition

@author Tasos “Zapotek” Laskos <tasos.laskos@arachni-scanner.com>

Constants

NON_PLAYABLE

Non-playable events.

ZERO_DEPTH

Events without a DOM depth.

Attributes

element[R]

@return [Browser::ElementLocator]

HTML element which received the {#event}.
event[R]

@return [Symbol]

Event triggered on {#element}.
options[R]

@return [Hash]

Extra options.
time[RW]

@return [Float]

Time it took to trigger the given {#event} on the {#element}.

Public Class Methods

from_rpc_data( data ) click to toggle source

@param [Hash] data {#to_rpc_data} @return [Transition]

# File lib/arachni/page/dom/transition.rb, line 266
def self.from_rpc_data( data )
    instance = allocate
    data.each do |name, value|

        value = case name
                    when 'event'
                        value.to_sym

                    when 'element'
                        if value.is_a? String
                            data['event'].to_s == 'request' ? value : value.to_sym
                        else
                            Browser::ElementLocator.from_rpc_data( value )
                        end

                    when 'options'
                        value.my_symbolize_keys(false)

                    else
                        value
                end

        instance.instance_variable_set( "@#{name}", value )
    end
    instance
end
new( *args, &block ) click to toggle source

@note If arguments are provided they will be passed to {#start}.

@param (see start)

@raise [Error::Completed]

When the transition has been marked as completed.

@raise [Error::Running]

When the transition has already been marked as running.

@raise [Error::InvalidElement]

When an element of invalid type is passed.
# File lib/arachni/page/dom/transition.rb, line 102
def initialize( *args, &block )
    @options = {}

    return if !args.any?
    start( *args, &block )
end

Public Instance Methods

==( other ) click to toggle source
# File lib/arachni/page/dom/transition.rb, line 297
def ==( other )
    hash == other.hash
end
complete() click to toggle source

@note Will stop the timer for {#time}.

Marks the transition as finished.

@return [Transition]

`self`

@raise [Error::Completed]

When the transition has already been marked as completed.

@raise [Error::NotRunning]

When the transition is not running.
# File lib/arachni/page/dom/transition.rb, line 166
def complete
    fail Error::Completed, 'Transition has completed.'   if completed?
    fail Error::NotRunning, 'Transition is not running.' if !running?

    @time  = Time.now - @clock
    @clock = nil

    self
end
completed?() click to toggle source

@return [Bool]

`true` if the transition has completed, `false` otherwise.

@see initialize @see start @see complete

# File lib/arachni/page/dom/transition.rb, line 222
def completed?
    !!@time
end
depth() click to toggle source

@return [Integer]

Depth for this transition.

@see ZERO_DEPTH

# File lib/arachni/page/dom/transition.rb, line 180
def depth
    ZERO_DEPTH.include?( event ) ? 0 : 1
end
dup() click to toggle source
# File lib/arachni/page/dom/transition.rb, line 240
def dup
    rpc_clone
end
event=( event ) click to toggle source

@param [String, Symbol] event

Event associated with this transition -- will be converted to `Symbol`.

@return [Symbol]

# File lib/arachni/page/dom/transition.rb, line 113
def event=( event )
    @event = event.to_s.to_sym
end
hash() click to toggle source
# File lib/arachni/page/dom/transition.rb, line 293
def hash
    to_hash.tap { |h| h.delete :time }.hash
end
play( browser ) click to toggle source

@param [Browser] browser

Browser to use to play the transition.

@return [Transition, nil]

New transition as a result of the play, `nil` if the play wasn't
successful.

@raise [Error::NotPlayable]

When the transition is not {#playable?}.
# File lib/arachni/page/dom/transition.rb, line 193
def play( browser )
    fail Error::NotPlayable, "Transition is not playable: #{self}" if !playable?

    if element == :page && event == :load
        return browser.goto( options[:url],
            cookies:         options[:cookies],
            take_snapshot:   false
        )
    end

    browser.fire_event element, event, options
end
playable?() click to toggle source

@return [Bool]

`true` if the transition is for an event that can be played, `false`
otherwise.

@see NON_PLAYABLE

# File lib/arachni/page/dom/transition.rb, line 231
def playable?
    !NON_PLAYABLE.include?( event )
end
running?() click to toggle source

@return [Bool]

`true` if the transition is in progress, `false` otherwise.

@see initialize @see start @see complete

# File lib/arachni/page/dom/transition.rb, line 212
def running?
    !!@clock
end
start( element, event, options = {}, &block ) click to toggle source

@note Will start the timer for {#time}.

@param [Browser::ElementLocator] element @param [Symbol] event @param [Hash] options

Extra options to associate with this transition.

@param [Block] block

If a `block` has been given it will be executed and the transition will
automatically be marked as {#complete finished}.

@return [Transition] ‘self`

@raise [Error::Completed]

When the transition has been marked as completed.

@raise [Error::Running]

When the transition has already been marked as running.

@raise [Error::InvalidElement]

When an element of invalid type is passed.
# File lib/arachni/page/dom/transition.rb, line 135
def start( element, event, options = {}, &block )
    fail Error::Completed, 'Transition has completed.'   if completed?
    fail Error::Running, 'Transition is already running' if running?

    if ![Symbol, String, Browser::ElementLocator].include?( element.class )
        fail Error::InvalidElement
    end

    self.event = event
    @element   = element

    @options = options.my_symbolize_keys(false)
    @clock   = Time.now

    return self if !block_given?

    block.call
    complete
end
to_h()
Alias for: to_hash
to_hash() click to toggle source

@return [Hash]

# File lib/arachni/page/dom/transition.rb, line 245
def to_hash
    {
        element: element.is_a?( Browser::ElementLocator ) ?
                     element.to_h : element,
        event:   event,
        options: options,
        time:    time
    }
end
Also aliased as: to_h
to_rpc_data() click to toggle source

@return [Hash]

Data representing this instance that are suitable the RPC transmission.
# File lib/arachni/page/dom/transition.rb, line 258
def to_rpc_data
    h = to_hash.my_stringify_keys(false)
    h['element'] = element.to_rpc_data_or_self
    h
end
to_s() click to toggle source

@return [String]

# File lib/arachni/page/dom/transition.rb, line 236
def to_s
    "[#{time.to_f}s] '#{event}' on: #{element}"
end