1# Copyright 2015 The Chromium OS Authors. All rights reserved.
2# Use of this source code is governed by a BSD-style license that can be
3# found in the LICENSE file.
4
5"""An interface to access the local browser facade."""
6
7import logging
8
9class BrowserFacadeNativeError(Exception):
10    """Error in BrowserFacadeNative."""
11    pass
12
13
14class BrowserFacadeNative(object):
15    """Facade to access the browser-related functionality."""
16
17    def __init__(self, resource):
18        """Initializes the USB facade.
19
20        @param resource: A FacadeResource object.
21
22        """
23        self._resource = resource
24
25
26    def start_custom_chrome(self, kwargs):
27        """Start a custom Chrome with given arguments.
28
29        @param kwargs: A dict of keyword arguments passed to Chrome.
30        @return: True on success, False otherwise.
31
32        """
33        return self._resource.start_custom_chrome(kwargs)
34
35
36    def start_default_chrome(self, restart=False, extra_browser_args=None):
37        """Start the default Chrome.
38
39        @param restart: True to start Chrome without clearing previous state.
40        @param extra_browser_args: A list containing extra browser args passed
41                                   to Chrome in addition to default ones.
42        @return: True on success, False otherwise.
43
44        """
45        return self._resource.start_default_chrome(restart, extra_browser_args)
46
47
48    def new_tab(self, url):
49        """Opens a new tab and loads URL.
50
51        @param url: The URL to load.
52        @return a str, the tab descriptor of the opened tab.
53
54        """
55        logging.debug('Load URL %s', url)
56        return self._resource.load_url(url)
57
58
59    def close_tab(self, tab_descriptor):
60        """Closes a previously opened tab.
61
62        @param tab_descriptor: Indicate which tab to be closed.
63
64        """
65        tab = self._resource.get_tab_by_descriptor(tab_descriptor)
66        logging.debug('Closing URL %s', tab.url)
67        self._resource.close_tab(tab_descriptor)
68
69
70    def wait_for_javascript_expression(
71            self, tab_descriptor, expression, timeout):
72        """Waits for the given JavaScript expression to be True on the
73        given tab.
74
75        @param tab_descriptor: Indicate on which tab to wait for the expression.
76        @param expression: Indiate for what expression to wait.
77        @param timeout: Indicate the timeout of the expression.
78        """
79        self._resource.wait_for_javascript_expression(
80                tab_descriptor, expression, timeout)
81
82
83    def execute_javascript(self, tab_descriptor, statement, timeout):
84        """Executes a JavaScript statement on the given tab.
85
86        @param tab_descriptor: Indicate on which tab to execute the statement.
87        @param statement: Indiate what statement to execute.
88        @param timeout: Indicate the timeout of the statement.
89        """
90        self._resource.execute_javascript(
91                tab_descriptor, statement, timeout)
92
93
94    def evaluate_javascript(self, tab_descriptor, expression, timeout):
95        """Evaluates a JavaScript expression on the given tab.
96
97        @param tab_descriptor: Indicate on which tab to evaluate the expression.
98        @param expression: Indiate what expression to evaluate.
99        @param timeout: Indicate the timeout of the expression.
100        @return the JSONized result of the given expression
101        """
102        return self._resource.evaluate_javascript(
103                tab_descriptor, expression, timeout)
104