openapi: 3.0.0

info:
  title: CulebraTester
  description: >
    ## Snaky Android Test

    ---

    If you want to be able to try out the API using the **Execute** or **TRY** button from this page

    - an android device should be connected using `adb`

    - the server should have been started using `./culebratester2 start-server`


    then you will be able to invoke the API and see the responses.

  version: 2.0.12

servers:
  - url: "http://localhost:9987/v2"

paths:
  /culebra/help/{api}:
    get:
      summary: Gets help
      description: Gets help info about the *API* specified as parameter.
        For example you can obtain information about

        * /uiDevice/click

        * /device/displayRealSize

        * /uiDevice/screenshot

        * etc.
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Help"
        default:
          $ref: '#/components/responses/error'
    parameters:
      - name: api
        in: path
        description: Specify the API help is about
        required: true
        schema:
          type: string


  /culebra/info:
    get:
      summary: Gets information about this app
      description: Gets information about this app
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CulebraInfo'
        default:
          $ref: '#/components/responses/error'


  /device/displayRealSize:
    get:
      summary: Gets display real size
      description: Gets the display real size
      responses:
        200:
          description: Display real size
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DisplayRealSize"
        default:
          $ref: '#/components/responses/error'


  /targetContext/startActivity:
    get:
      summary: Starts an Activity
      description: Starts an Activity
      parameters:
        - name: "pkg"
          in: query
          required: true
          description: the package name
          schema:
            type: string
        - name: "cls"
          in: query
          required: true
          description: the class name
          schema:
            type: string
      responses:
        200:
          $ref: '#/components/responses/ok'
        default:
          $ref: '#/components/responses/error'


  /objectStore/list:
    get:
      summary: Lists the objects in store
      description: Lists the objects in store
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    oid:
                      type: integer
                    object:
                      type: object
        default:
          $ref: '#/components/responses/error'

  /uiDevice/dumpWindowHierarchy:
    get:
      summary: Dumps the window hierarchy
      description: Dumps the window hierarchy
      parameters:
        - name: format
          in: query
          required: false
          description: the output format
          schema:
            type: string
      responses:
        200:
          description: Window hierarchy
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WindowHierarchy"
            application/xml:
              schema:
                $ref: "#/components/schemas/WindowHierarchy"
        default:
          $ref: '#/components/responses/error'


  /uiDevice/click:
    get:
      summary: Clicks at the specified location
      description: Clicks at the specified location
      parameters:
        - name: "x"
          in: query
          required: true
          description: x coordinate
          schema:
            type: integer
            minimum: 0
        - name: "y"
          in: query
          required: true
          description: y coordinate
          schema:
            type: integer
            minimum: 0
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StatusResponse"

            text/plain:
              schema:
                type: string
              example: OK
        default:
          $ref: '#/components/responses/error'


  /uiDevice/findObject:
    get:
      summary: Finds an object
      description: Finds an object. The object found, if any, can be later used in other call like API.click.
      parameters:
        - name: resourceId
          in: query
          description: the resource id
          example: 'com.android.calendar:id/d0_label'
          schema:
            type: string
        - name: uiSelector
          in: query
          description: the selector sets the resource name criteria for matching. A UI element will be considered a match if its resource name exactly matches the selector parameter and all other criteria for this selector are met.
            The format of the selector string is

              `sel@[$]value,...`

            Where `sel` can be one of
             - clazz or className
             - clickable
             - depth
             - desc
             - index
             - instance
             - package
             - parentIndex
             - res
             - scrollable
             - text

            `@` replaces the `=` sign that is used to separate parameters and values in the URL. If the first character of value is `$` then a `Pattern` is created.
          example: 'res@com.android.calendar:id/d0_label,instance@1'
          schema:
            type: string
        - name: bySelector
          in: query
          description: the selector sets the resource name criteria for matching. A UI element will be considered a match if its resource name exactly matches the selector parameter and all other criteria for this selector are met.
            The format of the selector string is

              `sel@[$]value,...`

            Where `sel` can be one of
             - checkable
             - clazz
             - clickable
             - depth
             - desc
             - package
             - res
             - scrollable
             - text

            `@` replaces the `=` sign that is used to separate parameters and values in the URL. If the first character of value is `$` then a `Pattern` is created.
          example: 'res@com.android.calendar:id/d0_label,depth@2'
          schema:
            type: string

      responses:
        200:
          description: Object found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ObjectRef'
              example:
                oid: 1
                className: 'android.widget.TextView'
        404:
          description: Object not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusResponse'
              example:
                status: ERROR
                errorStatusResponse: 1001
                errorMessage: Object not found
        default:
          $ref: '#/components/responses/error'

    post:
      summary: Finds an object
      description: Finds an object. The object found, if any, can be later used in other call like API.click.
      requestBody:
        description: Selector
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Selector'
      responses:
        200:
          description: Object found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ObjectRef'
              example:
                oid: 1
                className: 'android.widget.Button'
        404:
          description: Object not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusResponse'
              example:
                status: ERROR
                errorStatusResponse: 1001
                errorMessage: Object not found
        default:
          $ref: '#/components/responses/error'

  /uiDevice/findObjects:
    get:
      summary: Finds *all* objects that match the selector criteria.
      description: Finds an object. The object found, if any, can be later used in other call like API.click.
      parameters:
        - name: bySelector
          in: query
          description: the selector sets the resource name criteria for matching. A UI element will be considered a match if its resource name exactly matches the selector parameter and all other criteria for this selector are met.
            The format of the selector string is

              `sel@[$]value,...`

            Where `sel` can be one of
             - checkable
             - clazz
             - clickable
             - depth
             - desc
             - package
             - res
             - scrollable
             - text

            `@` replaces the `=` sign that is used to separate parameters and values in the URL. If the first character of value is `$` then a `Pattern` is created.
          example: 'res@com.android.calendar:id/d0_label,depth@2'
          schema:
            type: string
      responses:
        200:
          description: Objects found
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ObjectRef'
              example: [{'oid': 1, 'className': 'android.widget.Button'}, {'oid': 2, 'className': 'android.widget.TextView'}]
        404:
          description: Object not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusResponse'
              example:
                status: ERROR
                errorStatusResponse: 1001
                errorMessage: Object not found
        default:
          $ref: '#/components/responses/error'

  /uiDevice/currentPackageName:
    get:
      summary: Gets the current package name
      description: Gets the current package name
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CurrentPackageName'
        default:
          $ref: '#/components/responses/error'


  /uiDevice/displayHeight:
    get:
      summary: Gets the display height
      description: Gets the display height
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DisplayHeight'
        default:
          $ref: '#/components/responses/error'


  /uiDevice/displayRotation:
    get:
      summary: Gets the display rotation
      description: Gets the display rotation
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DisplayRotation'
        default:
          $ref: '#/components/responses/error'


  /uiDevice/displaySizeDp:
    get:
      summary: Gets the display size in DP
      description: Gets the display size in DP
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DisplaySizeDp'
        default:
          $ref: '#/components/responses/error'


  /uiDevice/displayWidth:
    get:
      summary: Gets the display width
      description: Gets the display width
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DisplayWidth'
        default:
          $ref: '#/components/responses/error'


  /uiDevice/lastTraversedText:
    get:
      summary: Retrieves the text from the last UI traversal event received.
      description: Retrieves the text from the last UI traversal event received.
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LastTraversedText'
        default:
          $ref: '#/components/responses/error'


  /uiDevice/productName:
    get:
      summary: Retrieves the product name of the device.
      description: Retrieves the product name of the device.
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProductName'
        default:
          $ref: '#/components/responses/error'


  /uiDevice/pressBack:
    get:
      summary: Simulates a short press on the BACK button.
      description: Simulates a short press on the BACK button.
      responses:
        200:
          $ref: '#/components/responses/ok'
        default:
          $ref: '#/components/responses/error'


  /uiDevice/pressDelete:
    get:
      summary: Simulates a short press on the DELETE key.
      description: Simulates a short press on the DELETE key.
      responses:
        200:
          $ref: '#/components/responses/ok'
        default:
          $ref: '#/components/responses/error'


  /uiDevice/pressEnter:
    get:
      summary: Simulates a short press on the ENTER key.
      description: Simulates a short press on the ENTER key.
      responses:
        200:
          $ref: '#/components/responses/ok'
        default:
          $ref: '#/components/responses/error'


  /uiDevice/pressHome:
    get:
      summary: Simulates a short press on the HOME button.
      description: Simulates a short press on the HOME button.
      responses:
        200:
          $ref: '#/components/responses/ok'
        default:
          $ref: '#/components/responses/error'


  /uiDevice/pressRecentApps:
    get:
      summary: Simulates a short press on the Recent Apps button.
      description: Simulates a short press on the Recent Apps button.
      responses:
        200:
          $ref: '#/components/responses/ok'
        default:
          $ref: '#/components/responses/error'


  /uiDevice/swipe:
    get:
      summary: Performs a swipe.
      description: Performs a swipe from one coordinate to another using the number of steps to determine smoothness and speed. Each step execution is throttled to 5ms per step. So for a 100 steps, the swipe will take about 1/2 second to complete.
      parameters:
        - name: startX
          description: from x
          in: query
          required: true
          schema:
            type: integer
            minimum: 0
        - name: startY
          description: from y
          in: query
          required: true
          schema:
            type: integer
            minimum: 0
        - name: endX
          description: to x
          in: query
          required: true
          schema:
            type: integer
            minimum: 0
        - name: endY
          description: end y
          in: query
          required: true
          schema:
            type: integer
            minimum: 0
        - name: steps
          description: is the number of move steps sent to the system
          in: query
          required: true
          schema:
            type: integer
            minimum: 0
      responses:
        200:
          $ref: '#/components/responses/ok'
        default:
          $ref: '#/components/responses/error'
    post:
      summary: Performs a swipe between points in the Point array.
      description: Each step execution is throttled to 5ms per step. So for a 100 steps, the swipe will take about 1/2 second to complete
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SwipeBody'
      responses:
        200:
          $ref: '#/components/responses/ok'
        default:
          $ref: '#/components/responses/error'

  /uiDevice/waitForIdle:
    get:
      summary: Waits for the current application to idle.
      description: Waits for the current application to idle.
      parameters:
        - name: timeout
          description: in milliseconds
          in: query
          schema:
            type: integer
            format: int64
            default: 10000
      responses:
        200:
          $ref: '#/components/responses/ok'
        default:
          $ref: '#/components/responses/error'


  /uiDevice/waitForWindowUpdate:
    get:
      summary: Waits for a window content update event to occur.
      description:  If a package name for the window is specified, but the current window does not have the same package name, the function returns immediately.
      parameters:
        - name: packageName
          description: the specified window package name (can be null or not present). If null, a window update from any front-end window will end the wait
          in: query
          required: false
          schema:
            type: string
        - name: timeout
          description: in milliseconds
          in: query
          required: true
          schema:
            type: integer
            format: int64
      responses:
        200:
          $ref: '#/components/responses/ok'
        default:
          $ref: '#/components/responses/error'


  /uiDevice/pressKeyCode:
    get:
      summary: Simulates a short press using a key code.
      description: Simulates a short press using a key code.
      parameters:
        - name: keyCode
          description: the key code of the event.
          in: query
          required: true
          schema:
            type: integer
        - name: metaState
          description: an integer in which each bit set to 1 represents a pressed meta key
          in: query
          required: false
          schema:
            type: integer
      responses:
        200:
          $ref: '#/components/responses/ok'
        default:
          $ref: '#/components/responses/error'


  /uiDevice/screenshot:
    get:
      summary: Gets the device screenshot
      description: >
        Gets the device screenshot and can be influenced by the parameters.
        For example the `scale` of the screenshot or its `quality` can be specified.
        **NOTE**: [`UiDevice.takeScreenshot()`](https://developer.android.com/reference/android/support/test/uiautomator/UiDevice.html#takeScreenshot(java.io.File,%20float,%20int)) usually ignores these parameters so expect no change.
      responses:
        200:
          description: OK
          content:
            image/png:
              schema:
                type: string
                format: binary
              examples:
                exernal-image-example:
                  summary: External example image
                  externalValue: "https://raw.githubusercontent.com/wiki/dtmilano/AndroidViewClient/images/emulator-launcher-shortcuts.png"
        400:
          description: Cannot obtain screenshot
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StatusResponse"
      parameters:
        - name: "scale"
          in: query
          required: false
          description: The scale of the screenshot (i.e. 0.5)
          schema:
            type: number
            format: float
            minimum: 0
            exclusiveMinimum: true
            maximum: 1.0
          example: 0.5
        - name: "quality"
          in: query
          required: false
          description: The quality of the screenshot (i.e. 100)
          schema:
            type: integer
            minimum: 1
            maximum: 100
          example: 90

  /uiObject2/{oid}/click:
    get:
      summary: Clicks on the specified object.
      description: The target object should have been found using `findObject` with a `selector`.
      parameters:
        - name: oid
          in: path
          required: true
          description: The object ID
          schema:
            type: integer
      responses:
        200:
          $ref: '#/components/responses/ok'
        default:
          $ref: '#/components/responses/error'


  /uiObject2/{oid}/dump:
    get:
      summary: Dumps the specified object.
      description: The target object should have been found using `findObject` with a `selector`.
      parameters:
        - name: oid
          in: path
          required: true
          description: The object ID
          schema:
            type: integer
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Selector'
        default:
          $ref: '#/components/responses/error'


  /uiObject2/{oid}/getText:
    get:
      summary: Gets the text content.
      description: The target object should have been found using `findObject` with a `selector`.
      parameters:
        - name: oid
          in: path
          required: true
          description: The object ID
          schema:
            type: integer
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Text'
        default:
          $ref: '#/components/responses/error'

  /uiObject2/{oid}/longClick:
    get:
      summary: Long-clicks on the specified object.
      description: The target object should have been found using `findObject` with a `selector`.
      parameters:
        - name: oid
          in: path
          required: true
          description: The object ID
          schema:
            type: integer
      responses:
        200:
          $ref: '#/components/responses/ok'
        default:
          $ref: '#/components/responses/error'

  /uiObject2/{oid}/setText:
    post:
      summary: Sets the text content if this object is an editable field.
      description: The target object should have been found using `findObject` with a `selector`.
      parameters:
        - name: oid
          in: path
          required: true
          description: The object ID
          schema:
            type: integer
      requestBody:
        description: Text to enter in the field
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                text:
                  type: string
      responses:
        200:
          $ref: '#/components/responses/ok'
        default:
          $ref: '#/components/responses/error'
components:
  schemas:
    StatusResponse:
      type: object
      required:
        - status
      properties:
        status:
          type: string
          enum:
            - OK
            - ERROR
            - UNKNOWKN
        statusCode:
          type: integer
        errorMessage:
          type: string
      example:
        status: ERROR
        statusCode: 100
        errorMessage: Operation could not be completed

    CulebraInfo:
      type: object
      properties:
        versionName:
          type: string
        versionCode:
          type: integer
      required:
        - versionName
        - versionCode

    CurrentPackageName:
      type: object
      properties:
        currentPackageName:
          type: string
          description: the current package name
      example:
        currentPackageName: 'com.android.calendar'

    DisplayHeight:
      type: object
      properties:
        displayHeight:
          type: integer
          description: the current display height
      example:
        displayHeight: 1776

    DisplayRotationEnum:
      type: integer
      description: the current display rotation
      # the generation of this enum is incorrect: i.e.: 0("0")
      enum:
        - 0
        - 180
        - 270
        - 90

    DisplayRotation:
      type: object
      properties:
        displayRotation:
          type: integer
          description: the current display rotation
          enum:
            - 0
            - 180
            - 270
            - 90
        # there no way of doing this
        #  schema:
        #    $ref: '#/components/schemas/DisplayRotation'
        # and even though, the generated enum is wrong
      example:
        displayRotation: 0

    DisplaySizeDp:
      type: object
      properties:
        displaySizeDpX:
          type: integer
          description: the display x in DP
        displaySizeDpY:
          type: integer
          description: the display y in DP
      example:
        displaySizeDpX: 2400
        displaySizeDpY: 1080

    DisplayWidth:
      type: object
      properties:
        displayWidth:
          type: integer
          description: the current display width
      example:
        displayHeight: 1080

    Help:
      type: object
      required:
        - text
      properties:
        text:
          type: string
      example:
        text: CulebraTester Help

    DisplayRealSize:
      type: object
      required:
        - device
        - x
        - y
      properties:
        device:
          type: string
        x:
          type: integer
        y:
          type: integer
        artWidth:
          type: integer
        artHeight:
          type: integer
        screenshotWidth:
          type: integer
        screenshotX:
          type: integer
        screenshotY:
          type: integer
      example:
          device: emulator
          x: 960
          y: 1080
          screenshotWidth: 960

    LastTraversedText:
      type: object
      properties:
        lastTraversedText:
          type: string
          description: text of the last traversal event, else return an empty string
      example:
        lastTraversedText: ""

    WindowHierarchyChild:
      type: object
      properties:
        id:
          type: integer
        parent:
          type: integer
        text:
          type: string
        package:
          type: string
        checkable:
          type: boolean
        clickable:
          type: boolean
        index:
          type: integer
        contentDescription:
          type: string
        focusable:
          type: boolean
        resourceId:
          type: string
        enabled:
          type: boolean
        password:
          type: boolean
        longClickable:
          type: boolean
        longText:
          type: string
        clazz:
          type: string
        scrollable:
          type: boolean
        selected:
          type: boolean
        checked:
          type: boolean
        focused:
          type: boolean
        bounds:
          type: array
          items:
            type: integer
        children:
          type: array
          items:
            $ref: '#/components/schemas/WindowHierarchyChild'
      example:
        $ref: '#/components/examples/windowHierarchyChild'

    WindowHierarchy:
      type: object
      properties:
        id:
          type: string
        text:
          type: string
        timestamp:
          type: string
        children:
          type: array
          items:
            $ref: '#/components/schemas/WindowHierarchyChild'
      example:
        id: "hierarchy"
        text: "Window Hierarchy"
        timestamp: "2020-01-15T06:11:10Z"
        children:
          - $ref: '#/components/examples/windowHierarchyChild'

    Selector:
      type: object
      properties:
        checkable:
          type: boolean
        clazz:
          type: string
        clickable:
          type: boolean
        depth:
          type: integer
        desc:
          type: string
        pkg:
          type: string
        res:
          type: string
        scrollable:
          type: boolean
        text:
          type: string
        index:
          type: integer
        instance:
          type: integer
      example:
        $ref: '#/components/examples/selector'

    ObjectRef:
      type: object
      properties:
        oid:
          type: integer
        className:
          type: string
      required:
        - oid

    Point:
      type: object
      properties:
        x:
          type: integer
        y:
          type: integer

    ProductName:
      type: object
      properties:
        productName:
          type: string
          description: product name of the device
      example:
        productName: "sailfish"

    Text:
      type: object
      properties:
        text:
          type: string
          description: the text in the object
      example:
        text: "lorem ipsum"

    SwipeBody:
      type: object
      properties:
        segments:
          type: array
          items:
            $ref: '#/components/schemas/Point'
        segmentSteps:
          type: integer
          minimum: 0

  examples:
    windowHierarchyChild:
      summary: A sample window hierarchy child
      value:
        id: 1
        parent: 0
        text: "android.widget.FrameLayout__ id=1 parent=0"
        package: "com.android.systemui"
        checkable: false
        clickable: false
        __index: 0
        contentDescription: "Some description"
        focusable: false
        resourceId: "id1"
        enabled: true
        password: false
        longClickable: false
        __text: "Some text"
        clazz: "android.widget.FrameLayout"
        scrollable: false
        selected: false
        bounds: [ 0, 1794, 1080, 1920 ]
        children: []

    errorStatusResponse:
      summary: Error status
      value:
        status: ERROR
        statusCode: 1001
        errorMessage: There was a problem

    selector:
      summary: Selector
      value:
        desc: "Equal"
        clazz: "android.widget.Button"
        depth: 1


  responses:
    ok:
      description: OK
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/StatusResponse'
          example:
            ststus: OK

    error:
      description: Operation was not successful
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/StatusResponse"
          example:
            status: ERROR
            statusCode: 1001
            errorMessage: There was a problem
  # does not work:
  #       example:
  #           $ref: '#/components/examples/errorStatusResponse'