1"use strict";(self.webpackChunktestplane_docs=self.webpackChunktestplane_docs||[]).push([["3058"],{9004(e,n,i){i.r(n),i.d(n,{metadata:()=>r,default:()=>p,frontMatter:()=>c,contentTitle:()=>a,toc:()=>d,assets:()=>l});var r=JSON.parse('{"id":"commands/browser/action","title":"action","description":"Overview {/ #overview /}","source":"@site/versioned_docs/version-v8/commands/browser/action.mdx","sourceDirName":"commands/browser","slug":"/commands/browser/action","permalink":"/docs/v8/commands/browser/action","draft":false,"unlisted":false,"editUrl":"https://github.com/gemini-testing/testplane-docs/tree/master/versioned_docs/version-v8/commands/browser/action.mdx","tags":[],"version":"v8","frontMatter":{},"sidebar":"mainSidebar","previous":{"title":"$$","permalink":"/docs/v8/commands/browser/_dollardollar"},"next":{"title":"actions","permalink":"/docs/v8/commands/browser/actions"}}'),o=i(74848),t=i(28453),s=i(77444);let c={},a="action",l={},d=[{value:"Overview",id:"overview",level:2},{value:"Keyboard Control",id:"keyboard_control",level:2},{value:"Special Symbols",id:"special_symbols",level:3},{value:"Usage Examples",id:"keyboard_examples",level:3},{value:"Pointer Control",id:"pointer_control",level:2},{value:"Usage Examples",id:"pointer_examples",level:3},{value:"Scroll Wheel Control",id:"scroll_wheel_control",level:2},{value:"Usage Examples",id:"scroll_examples",level:3},{value:"Related Commands",id:"related",level:2},{value:"References",id:"references",level:2}];function h(e){let n={a:"a",code:"code",h1:"h1",h2:"h2",h3:"h3",header:"header",li:"li",p:"p",pre:"pre",ul:"ul",...(0,t.R)(),...e.components};return(0,o.jsxs)(o.Fragment,{children:[(0,o.jsx)(n.header,{children:(0,o.jsx)(n.h1,{id:"action",children:"action"})}),"\n",(0,o.jsx)(n.h2,{id:"overview",children:"Overview"}),"\n",(0,o.jsxs)(n.p,{children:["Use the ",(0,o.jsx)(n.code,{children:"action"})," command to perform input actions on one of the virtualizable devices in the web browser."]}),"\n",(0,o.jsxs)(n.p,{children:["Unlike high-level commands like ",(0,o.jsx)(n.a,{href:"../../element/scrollIntoView",children:"scrollIntoView"})," and ",(0,o.jsx)(n.a,{href:"../../element/doubleClick",children:"doubleClick"}),", the Actions API provides more granular control of input devices. The following input sources are available:"]}),"\n",(0,o.jsxs)(n.ul,{children:["\n",(0,o.jsx)(n.li,{children:"text input for keyboard devices;"}),"\n",(0,o.jsx)(n.li,{children:"control of mouse, pen, or touch device;"}),"\n",(0,o.jsx)(n.li,{children:"scroll control for devices with a scroll wheel."}),"\n"]}),"\n",(0,o.jsxs)(n.p,{children:["Each chain of ",(0,o.jsx)(n.code,{children:"action"})," commands must end with a ",(0,o.jsx)(n.code,{children:"perform"})," command to execute the specified set of actions. This also releases all pressed keys, buttons, etc., on virtual input devices and triggers the necessary events. The release can be skipped by passing the argument ",(0,o.jsx)(n.code,{children:"true"})," to the ",(0,o.jsx)(n.code,{children:"perform"})," command. Example:"]}),"\n",(0,o.jsx)(n.pre,{children:(0,o.jsx)(n.code,{className:"language-typescript",children:"await browser.action(...).perform(true);\n"})}),"\n",(0,o.jsx)(s.A,{type:"info",children:(0,o.jsxs)(n.p,{children:["Support for this command and specific actions may vary depending on the execution environment.\nThe development progress can be tracked on ",(0,o.jsx)(n.a,{href:"https://wpt.fyi/results/webdriver/tests/perform_actions?label=experimental&label=master&aligned",children:"wpt.fyi"}),". For mobile devices,\nyou can use specialized gesture commands with ",(0,o.jsx)(n.a,{href:"http://appium.io",children:"Appium"})," on ",(0,o.jsx)(n.a,{href:"https://appium.github.io/appium-xcuitest-driver/latest/reference/execute-methods/#mobile-pinch",children:"iOS"})," and\n",(0,o.jsx)(n.a,{href:"https://github.com/appium/appium-uiautomator2-driver#mobile-gesture-commands",children:"Android"}),"."]})}),"\n",(0,o.jsx)(n.h2,{id:"keyboard_control",children:"Keyboard Control"}),"\n",(0,o.jsxs)(n.p,{children:["Used when specifying ",(0,o.jsx)(n.code,{children:"key"})," as the argument for the ",(0,o.jsx)(n.code,{children:"action"})," command. Example:"]}),"\n",(0,o.jsx)(n.pre,{children:(0,o.jsx)(n.code,{className:"language-typescript",children:'await browser.action("key");\n'})}),"\n",(0,o.jsxs)(n.p,{children:["Returns a ",(0,o.jsx)(n.code,{children:"KeyAction"})," object that supports the following actions:"]}),"\n",(0,o.jsxs)(n.ul,{children:["\n",(0,o.jsxs)(n.li,{children:[(0,o.jsx)(n.code,{children:"down(value: string)"})," \u2014 creates a key press action;"]}),"\n",(0,o.jsxs)(n.li,{children:[(0,o.jsx)(n.code,{children:"up(value: string)"})," \u2014 creates a key release action;"]}),"\n",(0,o.jsxs)(n.li,{children:[(0,o.jsx)(n.code,{children:"pause(ms: number)"})," \u2014 specifies that the input source does nothing for the specified amount of time."]}),"\n"]}),"\n",(0,o.jsx)(n.h3,{id:"special_symbols",children:"Special Symbols"}),"\n",(0,o.jsxs)(n.p,{children:["To use special symbols (",(0,o.jsx)(n.code,{children:"Control"}),", ",(0,o.jsx)(n.code,{children:"Page Up"}),", ",(0,o.jsx)(n.code,{children:"Shift"}),", etc.), you can use the ",(0,o.jsx)(n.code,{children:"Key"})," object from the ",(0,o.jsx)(n.a,{href:"https://www.npmjs.com/package/webdriverio",children:"webdriverio"})," package. It contains Unicode representations of all necessary special symbols. Example:"]}),"\n",(0,o.jsx)(n.pre,{children:(0,o.jsx)(n.code,{className:"language-typescript",children:'import { Key } from "webdriverio";\n\nawait browser.action("key").down(Key.Ctrl).perform();\n'})}),"\n",(0,o.jsx)(n.h3,{id:"keyboard_examples",children:"Usage Examples"}),"\n",(0,o.jsx)(n.pre,{children:(0,o.jsx)(n.code,{className:"language-typescript",children:'import { Key } from "webdriverio";\n\nit("should emit key events using key action commands", async ({ browser }) =>
1 {\n const elem = await browser.$("input");\n await elem.click(); // make the element active\n\n await browser.action("key").down("f").down("o").down("o").up("f").up("o").up("o").perform();\n\n console.log(await elem.getValue()); // returns "foo"\n\n // copy value from input element\n await browser.action("key").down(Key.Ctrl).down("c").pause(10).up(Key.Ctrl).up("c").perform();\n});\n'})}),"\n",(0,o.jsxs)(n.p,{children:["Instead of a series of ",(0,o.jsx)(n.code,{children:"down/up"})," events, it is better to use the ",(0,o.jsx)(n.code,{children:"setValue"})," command. The example is purely for demonstrating the principles of the ",(0,o.jsx)(n.code,{children:"action"})," command."]}),"\n",(0,o.jsx)(n.h2,{id:"pointer_control",children:"Pointer Control"}),"\n",(0,o.jsxs)(n.p,{children:["Used when specifying ",(0,o.jsx)(n.code,{children:"pointer"})," as the argument for the ",(0,o.jsx)(n.code,{children:"action"})," command, and you can also specify the pointer type. Example:"]}),"\n",(0,o.jsx)(n.pre,{children:(0,o.jsx)(n.code,{className:"language-typescript",children:'await browser.action("pointer", {\n parameters: { pointerType: "mouse" }, // "mouse" is the default value, also available: "pen" or "touch"\n});\n'})}),"\n",(0,o.jsxs)(n.p,{children:["Returns a ",(0,o.jsx)(n.code,{children:"PointerAction"})," object that supports the following actions:"]}),"\n",(0,o.jsxs)(n.ul,{children:["\n",(0,o.jsxs)(n.li,{children:[(0,o.jsx)(n.code,{children:"down(button: 'left' | 'middle' | 'right')"})," \u2014 creates an action to press a key;"]}),"\n",(0,o.jsxs)(n.li,{children:[(0,o.jsx)(n.code,{children:"down(params: PointerActionParams)"})," \u2014 creates an action to press a key with detailed parameters;"]}),"\n",(0,o.jsxs)(n.li,{children:[(0,o.jsx)(n.code,{children:"move(x: number, y: number)"})," \u2014 creates an action to move the pointer by ",(0,o.jsx)(n.code,{children:"x"})," and ",(0,o.jsx)(n.code,{children:"y"})," pixels relative to the viewport;"]}),"\n",(0,o.jsxs)(n.li,{children:[(0,o.jsx)(n.code,{children:"move(params: PointerActionMoveParams)"})," \u2014 creates an action to move the pointer by ",(0,o.jsx)(n.code,{children:"x"})," and ",(0,o.jsx)(n.code,{children:"y"})," pixels from the specified origin. The origin can be defined as the current pointer position, the viewport, or the center of a specific element;"]}),"\n",(0,o.jsxs)(n.li,{children:[(0,o.jsx)(n.code,{children:"up(button: 'left' | 'middle' | 'right')"})," \u2014 creates an action to release a key;"]}),"\n",(0,o.jsxs)(n.li,{children:[(0,o.jsx)(n.code,{children:"up(params: PointerActionUpParams)"})," \u2014 creates an action to release a key with detailed parameters;"]}),"\n",(0,o.jsxs)(n.li,{children:[(0,o.jsx)(n.code,{children:"cancel()"})," \u2014 creates an action that cancels the current pointer position;"]}),"\n",(0,o.jsxs)(n.li,{children:[(0,o.jsx)(n.code,{children:"pause(ms: number)"})," \u2014 specifies that the input source does nothing for the specified amount of time."]}),"\n"]}),"\n",(0,o.jsxs)(n.p,{children:["Detailed information on the parameter types ",(0,o.jsx)(n.a,{href:"https://github.com/webdriverio/webdriverio/blob/8ca026c75bf7c27ef9d574f0ec48d8bc13658602/packages/webdriverio/src/utils/actions/pointer.ts#L20-L35",children:"PointerActionParams"}),", ",(0,o.jsx)(n.a,{href:"https://github.com/webdriverio/webdriverio/blob/8ca026c75bf7c27ef9d574f0ec48d8bc13658602/packages/webdriverio/src/utils/actions/pointer.ts#L20-L42",children:"PointerActionMoveParams"}),", and ",(0,o.jsx)(n.a,{href:"https://github.com/webdriverio/webdriverio/blob/8ca026c75bf7c27ef9d574f0ec48d8bc13658602/packages/webdriverio/src/utils/actions/pointer.ts#L13-L19",children:"PointerActionUpParams"})," can be found in the webdriverio source code."]}),"\n",(0,o.jsx)(n.h3,{id:"pointer_examples",children:"Usage Examples"}),"\n",(0,o.jsx)(n.pre,{children:(0,o.jsx)(n.code,{className:"language-typescript",children:'it("drag and drop using pointer action command", async ({ browser }) => {\n const origin = await browser.$("#source");\n const targetOrigin = await browser.$("#target");\n\n await browser\n .action("pointer")\n .move({ duration: 0, origin, x: 0, y: 0 })\n .down({ button: 0 }) // left button\n .pause(10)\n .move({ duration: 0, origin: targetOrigin })\n .up({ button: 0 })\n .perform();\n});\n'})}),"\n",(0,o.jsx)(n.h2,{id:"scroll_wheel_control",children:"Scroll Wheel Control"}),"\n",(0,o.jsxs)(n.p,{children:["Used when specifying ",(0,o.jsx)(n.code,{children:"wheel"})," as the argument for the ",(0,o.jsx)(n.code,{children:"action"})," command. Example:"]}),"\n",(0,o.jsx)(n.pre,{children:(0,o.jsx)(n.code,{className:"language-typescript",children:'await browser.action("wheel");\n'})}),"\n",(0,o.jsxs)(n.p,{children:["Returns a ",(0,o.jsx)(n.code,{children:"WheelAction"})," object that supports the following actions:"]}),"\n",(0,o.jsxs)(n.ul,{children:["\n",(0,o.jsxs)(n.li,{children:[(0,o.jsx)(n.code,{children:"scroll(params: ScrollParam
1s)"})," \u2014 scrolls the page to the specified coordinates or origin;"]}),"\n",(0,o.jsxs)(n.li,{children:[(0,o.jsx)(n.code,{children:"pause(ms: number)"})," \u2014 specifies that the input source does nothing for the specified amount of time."]}),"\n"]}),"\n",(0,o.jsxs)(n.p,{children:["Detailed information on the parameter type ",(0,o.jsx)(n.a,{href:"https://github.com/webdriverio/webdriverio/blob/8ca026c75bf7c27ef9d574f0ec48d8bc13658602/packages/webdriverio/src/utils/actions/wheel.ts#L4-L29",children:"ScrollParams"})," can be found in the webdriverio source code."]}),"\n",(0,o.jsx)(n.h3,{id:"scroll_examples",children:"Usage Examples"}),"\n",(0,o.jsx)(n.pre,{children:(0,o.jsx)(n.code,{className:"language-typescript",children:'it("should scroll using wheel action commands", async ({ browser }) => {\n console.log(await browser.execute(() => window.scrollY)); // returns 0\n\n await browser\n .action("wheel")\n .scroll({\n deltaX: 0,\n deltaY: 500,\n duration: 200,\n })\n .perform();\n\n console.log(await browser.execute(() => window.scrollY)); // returns 500\n});\n'})}),"\n",(0,o.jsx)(n.h2,{id:"related",children:"Related Commands"}),"\n",(0,o.jsxs)(n.ul,{children:["\n",(0,o.jsx)(n.li,{children:(0,o.jsx)(n.a,{href:"../actions",children:"actions"})}),"\n"]}),"\n",(0,o.jsx)(n.h2,{id:"references",children:"References"}),"\n",(0,o.jsxs)(n.p,{children:["We'd like to give credit to the original WebdriverIO docs ",(0,o.jsx)(n.a,{href:"https://webdriver.io/docs/api/browser/action",children:"article"}),", from which we drew some information while writing our version."]})]})}function p(e={}){let{wrapper:n}={...(0,t.R)(),...e.components};return n?(0,o.jsx)(n,{...e,children:(0,o.jsx)(h,{...e})}):h(e)}},77444(e,n,i){i.d(n,{A:()=>k});var r=i(74848),o=i(96540),t=i(34164),s=i(30568),c=i(88287);function a({type:e,className:n,children:i,id:o}){return(0,r.jsx)("div",{className:(0,t.A)(c.G.common.admonition,c.G.common.admonitionType(e),"admonition_xJq3",n),id:o,children:i})}function l({icon:e,title:n}){return(0,r.jsxs)("div",{className:"admonitionHeading_Gvgb",children:[(0,r.jsx)("span",{className:"admonitionIcon_Rf37",children:e}),n]})}function d({children:e}){return e?(0,r.jsx)("div",{className:"admonitionContent_BuS1",children:e}):null}function h(e){let{type:n,icon:i,title:o,children:t,className:s,id:c}=e;return(0,r.jsxs)(a,{type:n,className:s,id:c,children:[o||i?(0,r.jsx)(l,{title:o,icon:i}):null,(0,r.jsx)(d,{children:t})]})}let p={icon:(0,r.jsx)(function(e){return(0,r.jsx)("svg",{viewBox:"0 0 14 16",...e,children:(0,r.jsx)("path",{fillRule:"evenodd",d:"M6.3 5.69a.942.942 0 0 1-.28-.7c0-.28.09-.52.28-.7.19-.18.42-.28.7-.28.28 0 .52.09.7.28.18.19.28.42.28.7 0 .28-.09.52-.28.7a1 1 0 0 1-.7.3c-.28 0-.52-.11-.7-.3zM8 7.99c-.02-.25-.11-.48-.31-.69-.2-.19-.42-.3-.69-.31H6c-.27.02-.48.13-.69.31-.2.2-.3.44-.31.69h1v3c.02.27.11.5.31.69.2.2.42.31.69.31h1c.27 0 .48-.11.69-.31.2-.19.3-.42.31-.69H8V7.98v.01zM7 2.3c-3.14 0-5.7 2.54-5.7 5.68 0 3.14 2.56 5.7 5.7 5.7s5.7-2.55 5.7-5.7c0-3.15-2.56-5.69-5.7-5.69v.01zM7 .98c3.86 0 7 3.14 7 7s-3.14 7-7 7-7-3.12-7-7 3.14-7 7-7z"})})},{}),title:(0,r.jsx)(s.A,{id:"theme.admonition.note",description:"The default label used for the Note admonition (:::note)",children:"note"})};function m(e){return(0,r.jsx)(h,{...p,...e,className:(0,t.A)("alert alert--secondary",e.className),children:e.children})}let u={icon:(0,r.jsx)(function(e){return(0,r.jsx)("svg",{viewBox:"0 0 12 16",...e,children:(0,r.jsx)("path",{fillRule:"evenodd",d:"M6.5 0C3.48 0 1 2.19 1 5c0 .92.55 2.25 1 3 1.34 2.25 1.78 2.78 2 4v1h5v-1c.22-1.22.66-1.75 2-4 .45-.75 1-2.08 1-3 0-2.81-2.48-5-5.5-5zm3.64 7.48c-.25.44-.47.8-.67 1.11-.86 1.41-1.25 2.06-1.45 3.23-.02.05-.02.11-.02.17H5c0-.06 0-.13-.02-.17-.2-1.17-.59-1.83-1.45-3.23-.2-.31-.42-.67-.67-1.11C2.44 6.78 2 5.65 2 5c0-2.2 2.02-4 4.5-4 1.22 0 2.36.42 3.22 1.19C10.55 2.94 11 3.94 11 5c0 .66-.44 1.78-.86 2.48zM4 14h5c-.23 1.14-1.3 2-2.5 2s-2.27-.86-2.5-2z"})})},{}),title:(0,r.jsx)(s.A,{id:"theme.admonition.tip",description:"The default label used for the Tip admonition (:::tip)",children:"tip"})};function x(e){return(0,r.jsx)(h,{...u,...e,className:(0,t.A)("alert alert--success",e.className),children:e.children})}let f={icon:(0,r.jsx)(function(e){return(0,r.jsx)("svg",{viewBox:"0 0 14 16",...e,children:(0,r.jsx)("path",{fillRule:"evenodd",d:"M7 2.3c3.14 0 5.7 2.56 5.7 5.7s-2.56 5.7-5.7 5.7A5.71 5.71 0 0 1 1.3 8c0-3.14 2.56-5.7 5.7-5.7zM7 1C3.14 1 0 4.14 0 8s3.14 7 7 7 7-3.14 7-7-3.14-7-7-7zm1 3H6v5h2V4zm0 6H6v2h2v-2z"})})},{}),title:(0,r.jsx)(s.A,{id:"theme.admonition.info",description:"The default label used for the Info admonition (:::info)",children:"info"})};function j(e){return(0,r.jsx)(h,{...f,...e,className:(0,t.A)("alert alert--info",e.className),children:e.children})}function v(e){return(0,r.jsx)("svg",{viewBox:"0 0 16 16",...e,children:(0,r.jsx)("path",{fillRule:"evenodd",d:"M8.893 1.5c-.183-.31-.52-.5-.887-.5s-.703.19-.886.5L.138 13.499a.98.98 0 0 0 0 1.001c.193.31.53.501.886.501h13.964c.367 0 .704-.19.877-.5a1.03 1.03 0 0 0 .01-1.002L8.893 1.5zm.133 11.497H6.987v-2.003h2.039v2.003zm0-3.004H6.987V5.987h2.039v4.006z"})})}let w={icon:(0,r.jsx)(v,{}),title:(0,r.jsx)(s.A,{id:"theme.admonition.warning",description:"The default label used for the Warning admonition (:::warning)",children:"warning"})},b={icon:(0,r.jsx)(function(e){return(0,r.jsx)("svg",{viewBox:"0 0 12 16",...e,children:(0,r.jsx)("path",{fillRule:"evenodd",d:"M5.05.31c.81 2.17.41 3.38-.52 4.31C3.55 5.67 1.98 6.45.9 7.98c-1.45 2.05-1.7 6.53 3.53 7.7-2.2-1.16-2.67-4.52-.3-6.61-.61 2.03.53 3.33 1.94 2.86 1.39-.47 2.3.53 2.27 1.67-.02.78-.31 1.44-1.13 1.81 3.42-.59 4.78-3.42 4.78-5.56 0-2.84-2.53-3.22-1.25-5.61-1.52.13-2.03 1.13-1.89 2.75.09 1.08-1.02 1.8-1.86 1.33-.67-.41-.66-1.19-.06-1.78C8.18 5.31 8.68 2.45 5.05.32L5.03.3l.02.01z"})})},{}),title:(0,r.jsx)(s.A,{id:"theme.admonition.danger",description:"The default label used for the Danger admonition (:::danger)",children:"danger"})},g={icon:(0,r.jsx)(v,{}),title:(0,r.jsx)(s.A,{id:"theme.admonition.caution",description:"The default label used for the Caution admonition (:::caution)",children:"caution"})},y={note:m,tip:x,info:j,warning:function(e){return(0,r.jsx)(h,{...w,...e,className:(0,t.A)("alert alert--warning",e.className),children:e.children})},danger:function(e){return(0,r.jsx)(h,{...b,...e,className:(0,t.A)("alert alert--danger",e.className),children:e.children})},secondary:e=>(0,r.jsx)(m,{title:"secondary",...e}),important:e=>(0,r.jsx)(j,{title:"important",...e}),success:e=>(0,r.jsx)(x,{title:"success",...e}),caution:function(e){return(0,r.jsx)(h,{...g,...e,className:(0,t.A)("alert alert--warning",e.className),children:e.children})}};function k(e){var n;let i,t=function(e){var n;let i,t,s,{mdxAdmonitionTitle:c,rest:a}=(n=e.children,t=(i=o.Children.toArray(n)).find(e=>o.isValidElement(e)&&"mdxAdmonitionTitle"===e.type),s=i.filter(e=>e!==t),{mdxAdmonitionTitle:t?.props.children,rest:s.length>0?(0,r.jsx)(r.Fragment,{children:s}):null}),l=e.title??c;return{...e,...l&&{title:l},children:a}}(e),s=(i=y[n=t.type])||(console.warn(`No admonition component found for admonition type "${n}". Using Info as fallback.`),y.info);return(0,r.jsx)(s,{...t})}},28453(e,n,i){i.d(n,{R:()=>s,x:()=>c});var r=i(96540);let o={},t=r.createContext(o);function s(e){let n=r.useContext(t);return r.useMemo(function(){return"function"==typeof e?e(n):{...n,...e}},[n,e])}function c(e){let n;return n=e.disableParentContext?"function"==typeof e.components?e.components(o):e.components||o:s(e.components),r.createElement(t.Provider,{value:n},e.children)}}}]);
Line numbers count LF bytes from the start of the resource, as the search results do. Vendor segments are library code the classifier recognised; they are stored but not indexed. Bytes are shown as Latin1 characters, one per byte.