API Docs for: 0.0.6
Show:

File: lib/commands/webdriver/element.js

  1. /*!
  2.  *
  3.  * Copyright (c) 2013 Sebastian Golasch
  4.  *
  5.  * Permission is hereby granted, free of charge, to any person obtaining a
  6.  * copy of this software and associated documentation files (the "Software"),
  7.  * to deal in the Software without restriction, including without limitation
  8.  * the rights to use, copy, modify, merge, publish, distribute, sublicense,
  9.  * and/or sell copies of the Software, and to permit persons to whom the
  10.  * Software is furnished to do so, subject to the following conditions:
  11.  *
  12.  * The above copyright notice and this permission notice shall be included
  13.  * in all copies or substantial portions of the Software.
  14.  *
  15.  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
  16.  * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  17.  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
  18.  * THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
  19.  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
  20.  * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
  21.  * DEALINGS IN THE SOFTWARE.
  22.  *
  23.  */
  24.  
  25. 'use strict';
  26.  
  27. /**
  28.  * Element related WebDriver endpoints
  29.  * see [JsonWireProtocol](https://code.google.com/p/selenium/wiki/JsonWireProtocol)
  30.  *
  31.  * @module FirefoxDriver
  32.  * @class Element
  33.  * @namespace FirefoxDriver.Commands.WebDriver
  34.  */
  35.  
  36. module.exports = function (Driver) {
  37.  
  38.   // check if the driver helper literal has been created yet
  39.   if (!Driver._helper) {
  40.     Driver._helper = {};
  41.   }
  42.  
  43.   // Helper
  44.   // ------
  45.  
  46.   /**
  47.    * Parses an element return value
  48.    *
  49.    * @method parseElement
  50.    * @param {object} element Marionette return value of an element call
  51.    * @return {object|number} Webdriver compatible element response
  52.    * @private
  53.    */
  54.  
  55.   Driver._helper.parseElement = function (element) {
  56.     element = JSON.parse(element);
  57.     return (!element.value) ? -1 : {ELEMENT: element.value.ELEMENT};
  58.   };
  59.  
  60.   /**
  61.    * Parses multi elements return value
  62.    *
  63.    * @method parseElements
  64.    * @param {object} element Marionette return value of an elements call
  65.    * @return {object|number} Webdriver compatible elements response
  66.    * @private
  67.    */
  68.  
  69.   Driver._helper.parseElements = function (elements) {
  70.     elements = JSON.parse(elements);
  71.     if (!elements.value) {
  72.       return -1;
  73.     }
  74.  
  75.     var dt = [];
  76.     elements.value.forEach(function (el) {
  77.       dt.push({ELEMENT: el});
  78.     });
  79.  
  80.     return dt;
  81.   };
  82.  
  83.   /**
  84.    * Generic multi elements response handler
  85.    *
  86.    * @method multiElementResponse
  87.    * @param {object} req Original request
  88.    * @param {object} res Original response
  89.    * @private
  90.    */
  91.  
  92.   Driver._helper.multiElementResponse = function (req, res, elements) {
  93.     var answer = {
  94.       sessionId: req.params.sessionId,
  95.       status: 0,
  96.       value: Driver._helper.parseElements(elements)
  97.     };
  98.  
  99.     res.status(200);
  100.     res.send(JSON.stringify(answer));
  101.   };
  102.  
  103.   /**
  104.    * Generic single element response handler
  105.    *
  106.    * @method singleElementResponse
  107.    * @param {object} req Original request
  108.    * @param {object} res Original response
  109.    * @private
  110.    */
  111.  
  112.   Driver._helper.singleElementResponse = function (req, res, element) {
  113.     var answer = {
  114.       sessionId: req.params.sessionId,
  115.       status: 0,
  116.       value: Driver._helper.parseElement(element)
  117.     };
  118.  
  119.     res.status(200);
  120.     res.send(JSON.stringify(answer));
  121.   };
  122.  
  123.   /**
  124.    * Search for an element on the page, starting from the document root.
  125.    * The located element will be returned as a WebElement JSON object.
  126.    *
  127.    * @method element
  128.    * @see https://code.google.com/p/selenium/wiki/JsonWireProtocol#/session/:sessionId/element
  129.    * @param {GET} sessionId ID of the session to route the command to
  130.    * @param {POST} using The locator strategy to use. // Not yet supported
  131.    * @param {POST} value The The search target.
  132.    */
  133.  
  134.   Driver.addCommand({
  135.     name: 'element',
  136.     url: '/session/:sessionId/element',
  137.     method: 'post',
  138.     onRequest: function (req, res) {
  139.       // load the marionette connection id & then request the session id
  140.       this.events.emit('marionette:cmd:element', {'sessionId': req.params.sessionId, 'selector': req.body.value});
  141.       this.events.on('marionette:cmd:element:response', Driver._helper.singleElementResponse.bind(this, req, res));
  142.     }
  143.   });
  144.  
  145.   /**
  146.    * Search for an element on the page, starting from the identified element.
  147.    * The located element will be returned as a WebElement JSON object.
  148.    * The table below lists the locator strategies that each server should support.
  149.    * Each locator must return the first matching element located in the DOM.
  150.    *
  151.    * @method childElement
  152.    * @see https://code.google.com/p/selenium/wiki/JsonWireProtocol#/session/:sessionId/:id/element
  153.    * @param {GET} sessionId ID of the session to route the command to
  154.    * @param {GET} elementId ID of the element to route the command to
  155.    * @param {POST} using The locator strategy to use. // Not yet supported
  156.    * @param {POST} value The The search target.
  157.    */
  158.  
  159.   Driver.addCommand({
  160.     name: 'childElement',
  161.     url: '/session/:sessionId/element/:elementId/element',
  162.     method: 'post',
  163.     onRequest: function (req, res) {
  164.       // load the marionette connection id & then request the session id
  165.       this.events.emit('marionette:cmd:childElement', {'sessionId': req.params.sessionId, 'elementId': req.params.elementId, 'selector': req.body.value});
  166.       this.events.on('marionette:cmd:childElement:response', Driver._helper.singleElementResponse.bind(this, req, res));
  167.     }
  168.   });
  169.  
  170.   /**
  171.    * Search for multiple elements on the page, starting from the document root.
  172.    * The located element will be returned as a WebElement JSON object.
  173.    *
  174.    * @method elements
  175.    * @see https://code.google.com/p/selenium/wiki/JsonWireProtocol#/session/:sessionId/elements
  176.    * @param {GET} sessionId ID of the session to route the command to
  177.    * @param {POST} using The locator strategy to use. // Not yet supported
  178.    * @param {POST} value The The search target.
  179.    */
  180.  
  181.   Driver.addCommand({
  182.     name: 'elements',
  183.     url: '/session/:sessionId/elements',
  184.     method: 'post',
  185.     onRequest: function (req, res) {
  186.       // load the marionette connection id & then request the session id
  187.       this.events.emit('marionette:cmd:elements', {'sessionId': req.params.sessionId, 'selector': req.body.value});
  188.       this.events.on('marionette:cmd:elements:response', Driver._helper.multiElementResponse.bind(this, req, res));
  189.     }
  190.   });
  191.  
  192.   /**
  193.    * Search for multiple elements on the page, starting from the identified element.
  194.    * The located elements will be returned as a WebElement JSON objects.
  195.    * The table below lists the locator strategies that each server should support.
  196.    * Elements should be returned in the order located in the DOM.
  197.    *
  198.    * @method childElements
  199.    * @see https://code.google.com/p/selenium/wiki/JsonWireProtocol#/session/:sessionId/elements/:id/elements
  200.    * @param {GET} sessionId ID of the session to route the command to
  201.    * @param {GET} elementId ID of the element to route the command to
  202.    * @param {POST} using The locator strategy to use. // Not yet supported
  203.    * @param {POST} value The The search target.
  204.    */
  205.  
  206.   Driver.addCommand({
  207.     name: 'childElements',
  208.     url: '/session/:sessionId/elements/:elementId/elements',
  209.     method: 'post',
  210.     onRequest: function (req, res) {
  211.       // load the marionette connection id & then request the session id
  212.       this.events.emit('marionette:cmd:childElements', {'sessionId': req.params.sessionId, 'elementId': req.params.elementId, 'selector': req.body.value});
  213.       this.events.on('marionette:cmd:childElements:response', Driver._helper.multiElementResponse.bind(this, req, res));
  214.     }
  215.   });
  216.  
  217.   /**
  218.    * Click on an element.
  219.    *
  220.    * @method click
  221.    * @see https://code.google.com/p/selenium/wiki/JsonWireProtocol#/session/:sessionId/element/:id/click
  222.    * @param {GET} sessionId ID of the session to route the command to
  223.    * @param {GET} elementId ID of the element to route the command to
  224.    */
  225.  
  226.   Driver.addCommand({
  227.     name: 'click',
  228.     url: '/session/:sessionId/element/:elementId/click',
  229.     method: 'post',
  230.     timeout: 1500
  231.   });
  232.  
  233.   /**
  234.    * Submit a FORM element.
  235.    * The submit command may also be applied to any element that is a descendant of a FORM element.
  236.    *
  237.    * @method submit
  238.    * @see https://code.google.com/p/selenium/wiki/JsonWireProtocol#/session/:sessionId/element/:id/submit
  239.    * @param {GET} sessionId ID of the session to route the command to
  240.    * @param {GET} elementId ID of the element to route the command to
  241.    */
  242.  
  243.   Driver.addCommand({
  244.     name: 'submit',
  245.     url: '/session/:sessionId/element/:elementId/submit',
  246.     method: 'post',
  247.     timeout: 1000
  248.   });
  249.  
  250.   /**
  251.    * Send a sequence of key strokes to an element
  252.    *
  253.    * @method value
  254.    * @see https://code.google.com/p/selenium/wiki/JsonWireProtocol#/session/:sessionId/element/:id/value
  255.    * @param {GET} sessionId ID of the session to route the command to
  256.    * @param {GET} elementId ID of the element to route the command to
  257.    * @param {POST} value The keys sequence to be sent
  258.    */
  259.  
  260.   Driver.addCommand({
  261.     name: 'val',
  262.     url: '/session/:sessionId/element/:elementId/value',
  263.     method: 'post',
  264.     params: {value: 'value'}
  265.   });
  266.  
  267.   /**
  268.    * Clears the contents of an element
  269.    *
  270.    * @method value
  271.    * @see https://code.google.com/p/selenium/wiki/JsonWireProtocol#/session/:sessionId/element/:id/value
  272.    * @param {GET} sessionId ID of the session to route the command to
  273.    * @param {GET} elementId ID of the element to route the command to
  274.    * @param {POST} value The keys sequence to be sent
  275.    */
  276.  
  277.   Driver.addCommand({
  278.     name: 'clear',
  279.     url: '/session/:sessionId/element/:elementId/clear',
  280.     method: 'post'
  281.   });
  282.  
  283.   Driver.addCommand({
  284.     name: 'submit',
  285.     url: '/session/:sessionId/element/:elementId/submit',
  286.     method: 'post'
  287.   });
  288.  
  289.   /**
  290.    * Send a sequence of key strokes to the active element.
  291.    * This command is similar to the send keys command in every aspect except the implicit termination:
  292.    * The modifiers are not released at the end of the call.
  293.    * Rather, the state of the modifier keys is kept between calls,
  294.    * so mouse interactions can be performed while modifier keys are depressed.
  295.    *
  296.    * @method keys
  297.    * @see https://code.google.com/p/selenium/wiki/JsonWireProtocol#/session/:sessionId/keys
  298.    * @param {GET} sessionId ID of the session to route the command to
  299.    * @param {POST} value  The keys sequence to be sent
  300.    */
  301.  
  302.   Driver.addCommand({
  303.     name: 'keys',
  304.     url: '/session/:sessionId/keys',
  305.     method: 'post',
  306.     params: {value: 'value'}
  307.   });
  308.  
  309.   /**
  310.    * Returns the visible text for the element.
  311.    *
  312.    * @method text
  313.    * @see https://code.google.com/p/selenium/wiki/JsonWireProtocol#/session/:sessionId/element/:id/text
  314.    * @param {GET} sessionId ID of the session to route the command to
  315.    * @param {GET} elementId ID of the element to route the command to
  316.    */
  317.  
  318.   Driver.addCommand({
  319.     name: 'text',
  320.     url: '/session/:sessionId/element/:elementId/text',
  321.     method: 'get'
  322.   });
  323.  
  324.   /**
  325.    * Get the value of an element's attribute.
  326.    *
  327.    * @method attribute
  328.    * @see https://code.google.com/p/selenium/wiki/JsonWireProtocol#/session/:sessionId/element/:id/attribute/:name
  329.    * @param {GET} sessionId ID of the session to route the command to
  330.    * @param {GET} elementId ID of the element to route the command to
  331.    * @param {GET} attr Attribute that should be fetched
  332.    */
  333.  
  334.   Driver.addCommand({
  335.     name: 'attribute',
  336.     url: '/session/:sessionId/element/:elementId/attribute/:attr',
  337.     method: 'get'
  338.   });
  339.  
  340.   /**
  341.    * Determine an element's location on the page.
  342.    * The point (0, 0) refers to the upper-left corner of the page.
  343.    * The element's coordinates are returned as a JSON object with x and y properties.
  344.    *
  345.    * @method displayed
  346.    * @see https://code.google.com/p/selenium/wiki/JsonWireProtocol#/session/:sessionId/element/:id/displayed
  347.    * @param {GET} sessionId ID of the session to route the command to
  348.    * @param {GET} elementId ID of the element to route the command to
  349.    */
  350.  
  351.   Driver.addCommand({
  352.     name: 'displayed',
  353.     url: '/session/:sessionId/element/:elementId/displayed',
  354.     method: 'get'
  355.   });
  356.  
  357.   /**
  358.    * Query for an element's tag name
  359.    *
  360.    * @method tagName
  361.    * @see https://code.google.com/p/selenium/wiki/JsonWireProtocol#GET_/session/:sessionId/element/:id/name
  362.    * @param {GET} sessionId ID of the session to route the command to
  363.    * @param {GET} elementId ID of the element to route the command to
  364.    */
  365.  
  366.   Driver.addCommand({
  367.     name: 'tagName',
  368.     url: '/session/:sessionId/element/:elementId/name',
  369.     method: 'get'
  370.   });
  371.  
  372.   /**
  373.    * Clear a TEXTAREA or text INPUT element's value
  374.    *
  375.    * @method clear
  376.    * @see https://code.google.com/p/selenium/wiki/JsonWireProtocol#POST_/session/:sessionId/element/:id/clear
  377.    * @param {GET} sessionId ID of the session to route the command to
  378.    * @param {GET} elementId ID of the element to route the command to
  379.    */
  380.  
  381.   Driver.addCommand({
  382.     name: 'clear',
  383.     url: '/session/:sessionId/element/:elementId/clear',
  384.     method: 'post'
  385.   });
  386.  
  387.   /**
  388.    * Determine if an OPTION element, or an INPUT element of type checkbox or radiobutton is currently selected
  389.    *
  390.    * @method selected
  391.    * @see https://code.google.com/p/selenium/wiki/JsonWireProtocol#GET_/session/:sessionId/element/:id/selected
  392.    * @param {GET} sessionId ID of the session to route the command to
  393.    * @param {GET} elementId ID of the element to route the command to
  394.    */
  395.  
  396.   Driver.addCommand({
  397.     name: 'selected',
  398.     url: '/session/:sessionId/element/:elementId/selected',
  399.     method: 'get'
  400.   });
  401.  
  402.   /**
  403.    * Determine if an element is currently enabled
  404.    *
  405.    * @method enabled
  406.    * @see https://code.google.com/p/selenium/wiki/JsonWireProtocol#GET_/session/:sessionId/element/:id/enabled
  407.    * @param {GET} sessionId ID of the session to route the command to
  408.    * @param {GET} elementId ID of the element to route the command to
  409.    */
  410.  
  411.   Driver.addCommand({
  412.     name: 'enabled',
  413.     url: '/session/:sessionId/element/:elementId/enabled',
  414.     method: 'get'
  415.   });
  416.  
  417.   /**
  418.    * Test if two element IDs refer to the same DOM element
  419.    *
  420.    * @method equals
  421.    * @see https://code.google.com/p/selenium/wiki/JsonWireProtocol#GET_/session/:sessionId/element/:id/equals/:other
  422.    * @param {GET} sessionId ID of the session to route the command to
  423.    * @param {GET} elementId ID of the element to route the command to
  424.    * @param {GET} other ID of the element to compare
  425.    */
  426.  
  427.   Driver.addCommand({
  428.     name: 'equals',
  429.     url: '/session/:sessionId/element/:elementId/equals/:other',
  430.     method: 'get'
  431.   });
  432.  
  433.   /**
  434.    * Determine an element's location on the page. The point (0, 0) refers to the upper-left corner of the page.
  435.    * The element's coordinates are returned as a JSON object with x and y properties.
  436.    *
  437.    * @method location
  438.    * @see https://code.google.com/p/selenium/wiki/JsonWireProtocol#GET_/session/:sessionId/element/:id/location
  439.    * @param {GET} sessionId ID of the session to route the command to
  440.    * @param {GET} elementId ID of the element to route the command to
  441.    */
  442.  
  443.   Driver.addCommand({
  444.     name: 'location',
  445.     url: '/session/:sessionId/element/:elementId/location',
  446.     method: 'get'
  447.   });
  448.  
  449.   /**
  450.    * Determine an element's location on the screen once it has been scrolled into view.
  451.    * Note: This is considered an internal command and should only be used to determine an element's location for correctly generating native events.
  452.    *
  453.    * @method locationInView
  454.    * @see https://code.google.com/p/selenium/wiki/JsonWireProtocol#GET_/session/:sessionId/element/:id/location_in_view
  455.    * @param {GET} sessionId ID of the session to route the command to
  456.    * @param {GET} elementId ID of the element to route the command to
  457.    */
  458.  
  459.   Driver.addCommand({
  460.     name: 'locationInView',
  461.     url: '/session/:sessionId/element/:elementId/location_in_view',
  462.     method: 'get'
  463.   });
  464.  
  465.   /**
  466.    * Determine an element's size in pixels.
  467.    * The size will be returned as a JSON object with width and height properties.
  468.    *
  469.    * @method size
  470.    * @see https://code.google.com/p/selenium/wiki/JsonWireProtocol#GET_/session/:sessionId/element/:id/size
  471.    * @param {GET} sessionId ID of the session to route the command to
  472.    * @param {GET} elementId ID of the element to route the command to
  473.    */
  474.  
  475.   Driver.addCommand({
  476.     name: 'size',
  477.     url: '/session/:sessionId/element/:elementId/size',
  478.     method: 'get'
  479.   });
  480.  
  481.   /**
  482.    * Get the element on the page that currently has focus.
  483.    * The element will be returned as a WebElement JSON object.
  484.    *
  485.    * @method active
  486.    * @see https://code.google.com/p/selenium/wiki/JsonWireProtocol#GET_/session/:sessionId/element/:id/active
  487.    * @param {GET} sessionId ID of the session to route the command to
  488.    * @param {GET} elementId ID of the element to route the command to
  489.    */
  490.  
  491.   Driver.addCommand({
  492.     name: 'active',
  493.     url: '/session/:sessionId/element/:elementId/active',
  494.     method: 'get'
  495.   });
  496.  
  497.   /**
  498.    * Get the element on the page that currently has focus.
  499.    * The element will be returned as a WebElement JSON object.
  500.    *
  501.    * @method elementInfo
  502.    * @see https://code.google.com/p/selenium/wiki/JsonWireProtocol#GET_/session/:sessionId/element/:id
  503.    * @param {GET} sessionId ID of the session to route the command to
  504.    * @param {GET} elementId ID of the element to route the command to
  505.    */
  506.  
  507.   Driver.addCommand({
  508.     name: 'elementInfo',
  509.     url: '/session/:sessionId/element/:elementId',
  510.     method: 'get'
  511.   });
  512.  
  513.   /**
  514.    * Query the value of an element's computed CSS property.
  515.    * The CSS property to query should be specified using the CSS property name,
  516.    * not the JavaScript property name (e.g. background-color instead of backgroundColor).
  517.    *
  518.    * @method cssProperty
  519.    * @see https://code.google.com/p/selenium/wiki/JsonWireProtocol#GET_/session/:sessionId/element/:id/size
  520.    * @param {GET} sessionId ID of the session to route the command to
  521.    * @param {GET} elementId ID of the element to route the command to
  522.    * @param {GET} propertyName Name of the css property to fetch
  523.    */
  524.  
  525.   Driver.addCommand({
  526.     name: 'cssProperty',
  527.     url: '/session/:sessionId/element/:elementId/css/:propertyName',
  528.     method: 'get'
  529.   });
  530.  
  531. };
  532.  
  533.