# Funciones de la biblioteca disponibles para los scripts de valores controlados de Python que usan Selenium
<a name="CloudWatch_Synthetics_Canaries_Library_Python"></a>

Esta sección enumera las funciones de biblioteca Selenium disponibles para los scripts valores controlados de Python.

**Topics**
+ [Clases y funciones de biblioteca de Python y Selenium que se aplican a todos los canaries](#CloudWatch_Synthetics_Library_allcanaries_Python)
+ [Clases y funciones de biblioteca de Python y Selenium que se aplican solo a canaries de la UI](#CloudWatch_Synthetics_Library_Python_UIcanaries)

## Clases y funciones de biblioteca de Python y Selenium que se aplican a todos los canaries
<a name="CloudWatch_Synthetics_Library_allcanaries_Python"></a>

Las siguientes funciones de biblioteca de CloudWatch Synthetics para Python son útiles para todos los canaries.

**Topics**
+ [Clase SyntheticsConfiguration](#CloudWatch_Synthetics_Library_SyntheticsConfiguration_Python)
+ [Clase SyntheticsLogger](#CloudWatch_Synthetics_Library_SyntheticsLogger_Python)

### Clase SyntheticsConfiguration
<a name="CloudWatch_Synthetics_Library_SyntheticsConfiguration_Python"></a>

Se puede utilizar la clase SyntheticsConfiguration para configurar el comportamiento de las funciones de biblioteca de Synthetics. Por ejemplo, puede utilizar esta clase para configurar la función ` executeStep()` para no tomar capturas de pantalla.

Se pueden establecer las configuraciones de CloudWatch Synthetics a nivel global.

Definiciones de la función

#### set\$1config(options)
<a name="CloudWatch_Synthetics_Library_setConfig_Python"></a>

```
from aws_synthetics.common import synthetics_configuration
```

` options ` es un objeto, que es un conjunto de opciones configurables para el valor controlado. En las siguientes secciones se explican los posibles campos en ` options `.
+ `screenshot_on_step_start` (booleano): si se debe tomar una captura de pantalla antes de comenzar un paso.
+ `screenshot_on_step_success` (booleano): si se debe tomar una captura de pantalla después de completar un paso correctamente.
+ `screenshot_on_step_failure` (booleano): si se debe tomar una captura de pantalla después de que un paso falla.

 **with\$1screenshot\$1on\$1step\$1start(screenshot\$1on\$1step\$1start)** 

Acepta un argumento booleano, que indica si se debe tomar una captura de pantalla antes de iniciar un paso.

 **with\$1screenshot\$1on\$1step\$1success(screenshot\$1on\$1step\$1success)** 

Acepta un argumento booleano, que indica si se debe tomar una captura de pantalla después de completar un paso correctamente.

 **with\$1screenshot\$1on\$1step\$1failure(screenshot\$1on\$1step\$1failure)** 

Acepta un argumento booleano, que indica si se debe tomar una captura de pantalla después de que un paso falla.

 **get\$1screenshot\$1on\$1step\$1start()** 

Muestra si se debe tomar una captura de pantalla antes de iniciar un paso.

 **get\$1screenshot\$1on\$1step\$1success()** 

Muestra si se debe realizar una captura de pantalla después de completar un paso correctamente.

 **get\$1screenshot\$1on\$1step\$1failure()** 

Muestra si se debe tomar una captura de pantalla después de que un paso falla.

 **disable\$1step\$1screenshots()** 

Desactiva todas las opciones de captura de pantalla (get\$1screenshot\$1on\$1step\$1start, get\$1screenshot\$1on\$1step\$1success, y get\$1screenshot\$1on\$1step\$1failure).

 **enable\$1step\$1screenshots()** 

Habilita todas las opciones de captura de pantalla (get\$1screenshot\$1on\$1step\$1start, get\$1screenshot\$1on\$1step\$1success y get\$1screenshot\$1on\$1step\$1failure). Estos métodos no están habilitados de forma predeterminada.

 **setConfig(options) con respecto a las métricas de CloudWatch** 

Para los canarios que utilizan `syn-python-selenium-1.1` o versiones posteriores, las **(opciones)** para **setConfig** pueden incluir los siguientes parámetros booleanos que determinan qué métricas publica el canario. El valor predeterminado para cada una de estas opciones es `true`. Las opciones que comienzan con ` aggregated` determinan si la métrica se emite sin la dimensión ` CanaryName`. Se pueden utilizar estas métricas para ver los resultados agregados de todos los canaries. Las otras opciones determinan si la métrica se emite con la dimensión `CanaryName`. Se pueden usar estas métricas para ver los resultados de cada valor controlado individualmente.

Para obtener una lista de las métricas de CloudWatch que los canaries emiten, consulte [Métricas de CloudWatch que los canaries publican](CloudWatch_Synthetics_Canaries_metrics.md).
+ `failed_canary_metric` (booleano): si se debe emitir la métrica ` Failed` (con la dimensión `CanaryName`) para este valor controlado. El valor predeterminado es `true`.
+ `failed_requests_metric` (booleano): si se debe emitir la métrica `Failed requests` (con la dimensión `CanaryName`) para este valor controlado. El valor predeterminado es `true`.
+ `2xx_metric` (booleano): si se debe emitir la métrica `2xx` (con la dimensión `CanaryName`) para este valor controlado. El valor predeterminado es `true`.
+ `4xx_metric` (booleano): si se debe emitir la métrica `4xx` (con la dimensión `CanaryName`) para este valor controlado. El valor predeterminado es `true`.
+ `5xx_metric` (booleano): si se debe emitir la métrica `5xx` (con la dimensión `CanaryName`) para este valor controlado. El valor predeterminado es `true`.
+ `step_duration_metric` (booleano): si se debe emitir la métrica `Step duration` (con las dimensiones `CanaryName` y `StepName`) para este valor controlado. El valor predeterminado es `true`.
+ `step_success_metric` (booleano): si se debe emitir la métrica `Step success` (con las dimensiones `CanaryName` y `StepName`) para este valor controlado. El valor predeterminado es `true`.
+ `aggregated_failed_canary_metric` (booleano): si se debe emitir la métrica `Failed` (sin la dimensión `CanaryName`) para este valor controlado. El valor predeterminado es `true`.
+ `aggregated_failed_requests_metric` (booleano): si se debe emitir la métrica `Failed Requests` (sin la dimensión `CanaryName`) para este valor controlado. El valor predeterminado es `true`.
+ `aggregated_2xx_metric` (booleano): si se debe emitir la métrica ` 2xx` (sin la dimensión `CanaryName`) para este valor controlado. El valor predeterminado es `true`.
+ `aggregated_4xx_metric` (booleano): si se debe emitir la métrica ` 4xx` (sin la dimensión `CanaryName`) para este valor controlado. El valor predeterminado es `true`.
+ `aggregated_5xx_metric` (booleano): si se debe emitir la métrica ` 5xx` (sin la dimensión `CanaryName`) para este valor controlado. El valor predeterminado es `true`.

 **with\$12xx\$1metric(2xx\$1metric)** 

Acepta un argumento booleano, que especifica si se emitirá una métrica `2xx` con la dimensión `CanaryName` para este valor controlado.

 **with\$14xx\$1metric(4xx\$1metric)** 

Acepta un argumento booleano, que especifica si se emitirá una métrica `4xx` con la dimensión `CanaryName` para este valor controlado.

 **with\$15xx\$1metric(5xx\$1metric)** 

Acepta un argumento booleano, que especifica si se emitirá una métrica `5xx` con la dimensión `CanaryName` para este valor controlado.

 **withAggregated2xxMetric(aggregated2xxMetric)** 

Acepta un argumento booleano, que especifica si se emitirá una métrica `2xx` sin dimensión para este valor controlado.

 **withAggregated4xxMetric(aggregated4xxMetric)** 

Acepta un argumento booleano, que especifica si se emitirá una métrica `4xx` sin dimensión para este valor controlado.

 **with\$1aggregated\$15xx\$1metric(aggregated\$15xx\$1metric)** 

Acepta un argumento booleano, que especifica si se emitirá una métrica `5xx` sin dimensión para este valor controlado.

 ** with\$1aggregated\$1failed\$1canary\$1metric(aggregated\$1failed\$1canary\$1metric)** 

Acepta un argumento booleano, que especifica si se emitirá una métrica `Failed` sin dimensión para este valor controlado.

 ** with\$1aggregated\$1failed\$1requests\$1metric(aggregated\$1failed\$1requests\$1metric)** 

Acepta un argumento booleano, que especifica si se emitirá una métrica `Failed requests` sin dimensión para este valor controlado.

 **with\$1failed\$1canary\$1metric(failed\$1canary\$1metric)** 

Acepta un argumento booleano, que especifica si se emitirá una métrica `Failed` con la dimensión `CanaryName` para este valor controlado.

 **with\$1failed\$1requests\$1metric(failed\$1requests\$1metric)** 

Acepta un argumento booleano, que especifica si se emitirá una métrica `Failed requests` con la dimensión `CanaryName` para este valor controlado.

 **with\$1step\$1duration\$1metric(step\$1duration\$1metric)** 

Acepta un argumento booleano, que especifica si se emitirá una métrica `Duration` con la dimensión `CanaryName` para este valor controlado.

 **with\$1step\$1success\$1metric(step\$1success\$1metric)** 

Acepta un argumento booleano, que especifica si se emitirá una métrica `StepSuccess` con la dimensión `CanaryName` para este valor controlado.

##### Métodos para habilitar o desactivar métricas
<a name="CloudWatch_Synthetics_Python_setConfig_metrics"></a>

 **disable\$1aggregated\$1request\$1metrics()** 

Desactiva que el valor controlado emita todas las métricas de solicitud que se emiten sin dimensión ` CanaryName`.

 **disable\$1request\$1metrics()** 

Deshabilita todas las métricas de solicitud, incluidas las métricas por valor controlado y las métricas agregadas en todos los valores controlados.

 **disable\$1step\$1metrics()** 

Desactiva todas las métricas de pasos, incluidas las métricas de éxito y de duración de los pasos.

 **enable\$1aggregated\$1request\$1metrics()** 

Permite que el valor controlado emita todas las métricas de solicitud que se emiten sin dimensión ` CanaryName`.

 **enable\$1request\$1metrics()** 

Habilita todas las métricas de solicitud, incluidas las métricas por valor controlado y las métricas agregadas en todos los valores controlados.

 **enable\$1step\$1metrics()** 

Habilita todas las métricas de pasos, incluidas las métricas de éxito y de duración de los pasos.

 **Uso en valores controlados de la IU** 

Primero, importe la relación de Synthetics y obtenga la configuración. A continuación, establezca la configuración para cada opción mediante llamadas al método SetConfig con una de las siguientes opciones.

```
from aws_synthetics.common import synthetics_configuration

synthetics_configuration.set_config(
     {
        "screenshot_on_step_start": False,
        "screenshot_on_step_success": False,
        "screenshot_on_step_failure": True
     }
)

or
```

O

```
synthetics_configuration.with_screenshot_on_step_start(False).with_screenshot_on_step_success(False).with_screenshot_on_step_failure(True)
```

Para desactivar todas las capturas de pantalla, utilice la función disableStepScreenshots() como en este ejemplo.

```
synthetics_configuration.disable_step_screenshots()
```

Puede habilitar y desactivar las capturas de pantalla en cualquier punto del código. Por ejemplo, para desactivar las capturas de pantalla solo para un paso, se deben desactivar antes de ejecutar ese paso y habilitarlas después del paso.

##### set\$1config(options) para los valores controlados de la interfaz de usuario
<a name="CloudWatch_Synthetics_Library_Python_UI"></a>

A partir de `syn-python-selenium-1.1`, para los valores controlados de la interfaz de usuario, ` set_config` puede incluir los siguientes parámetros booleanos:
+ `continue_on_step_failure` (booleano): si se debe continuar con la ejecución del script canario después de que un paso falle (este parámetro hace referencia a la función **executeStep**). Si algún paso falla, la ejecución del valor controlado seguirá marcándose como fallida. El valor predeterminado es `false`.

### Clase SyntheticsLogger
<a name="CloudWatch_Synthetics_Library_SyntheticsLogger_Python"></a>

`synthetics_logger` ingresa los registros tanto en la consola como en un archivo de registros local, en el mismo nivel de registro. Este archivo de registro se escribe en ambas ubicaciones solo si el nivel de registro coincide con el deseado para la función de registro a la que se llamó o está por debajo de este.

Los valores “DEBUG:”, “INFO:”, etc. se anteponen a las instrucciones de registro del archivo de registro local para que coincidan con el nivel de registro de la función a la que se llamó.

No es necesario utilizar `synthetics_logger` para crear un archivo de registros que se carga en la ubicación de resultados de Amazon S3. En su lugar, puede crear un archivo de registro distinto en la carpeta `/tmp`. Los archivos creados en la carpeta `/tmp` se cargan en la ubicación de resultados del bucket de S3 como artefactos.

Para utilizar . `synthetics_logger`:

```
from aws_synthetics.common import synthetics_logger
```

****Definiciones de funciones útiles:

Obtenga el nivel de registro:

```
log_level = synthetics_logger.get_level()
```

Establezca el nivel de registro:

```
synthetics_logger.set_level()
```

Registre un mensaje con un nivel especificado. El nivel puede ser `DEBUG`, ` INFO`, `WARN` o `ERROR`, como en los siguientes ejemplos de sintaxis:

```
synthetics_logger.debug(message, *args, **kwargs)
```

```
synthetics_logger.info(message, *args, **kwargs)
```

```
synthetics_logger.log(message, *args, **kwargs)
```

```
synthetics_logger.warning(message, *args, **kwargs)
```

```
synthetics_logger.error(message, *args, **kwargs)
```

Para obtener información acerca de los parámetros de depuración, consulte los documentos estándar de Python en [logging.debug](https://docs.python.org/3/library/logging.html#logging.debug)

En estas funciones de registro, el `message` es la cadena del formato del mensaje. Los `args` son los argumentos que se fusionan en `msg` que usan el operador de formato de cadena.

Hay tres argumentos de palabras clave en `kwargs`:
+ `exc_info`: si no se evalúa como false, agrega información de excepción al mensaje de registro.
+ `stack_info`: el valor predeterminado es false. Si es VERDADERO, agrega información de pila al mensaje de registro, incluida la llamada de registro real.
+ `extra`: el tercer argumento opcional de palabra clave, que se puede utilizar para especificar un diccionario que se utiliza para rellenar el `__dict__` del `LogRecord` que se ha creado para el evento de registro con atributos definidos por el usuario.

Ejemplos:

Registre un mensaje con el nivel `DEBUG`:

```
synthetics_logger.debug('Starting step - login.')
```

Registre un mensaje con el nivel `INFO`. `logger.log` es sinónimo de `logger.info`:

```
synthetics_logger.info('Successfully completed step - login.')
```

o

```
synthetics_logger.log('Successfully completed step - login.')
```

Registre un mensaje con el nivel `WARN`:

```
synthetics_logger.warning('Warning encountered trying to publish %s', 'CloudWatch Metric')
```

Registre un mensaje con el nivel `ERROR`:

```
synthetics_logger.error('Error encountered trying to publish %s', 'CloudWatch Metric')
```

Registre una excepción:

```
synthetics_logger.exception(message, *args, **kwargs)
```

Registre un mensaje con nivel `ERROR`. La información de excepción se agrega al mensaje de registro. Debe llamar a esta función solo desde un controlador de excepciones.

Para obtener información acerca de los parámetros de excepción, consulte los documentos estándar de Python en [logging.exception](https://docs.python.org/3/library/logging.html#logging.exception)

El `message` es la cadena en formato de mensaje. Los `args` son los argumentos, que se fusionan en `msg` mediante el operador de formato de cadena.

Hay tres argumentos de palabras clave en `kwargs`:
+ `exc_info`: si no se evalúa como false, agrega información de excepción al mensaje de registro.
+ `stack_info`: el valor predeterminado es false. Si es VERDADERO, agrega información de pila al mensaje de registro, incluida la llamada de registro real.
+ `extra`: el tercer argumento opcional de palabra clave, que se puede utilizar para especificar un diccionario que se utiliza para rellenar el `__dict__` del `LogRecord` que se ha creado para el evento de registro con atributos definidos por el usuario.

Ejemplo:

```
synthetics_logger.exception('Error encountered trying to publish %s', 'CloudWatch Metric')
```

## Clases y funciones de biblioteca de Python y Selenium que se aplican solo a canaries de la UI
<a name="CloudWatch_Synthetics_Library_Python_UIcanaries"></a>

Las siguientes funciones de la biblioteca de Selenium de CloudWatch Synthetics para Python solo son útiles para los valores controlados de la UI.

**Topics**
+ [Clase SyntheticsBrowser](#CloudWatch_Synthetics_Library_Python_SyntheticsBrowser)
+ [Clase SyntheticsWebDriver](#CloudWatch_Synthetics_Library_Python_SyntheticsWebDriver)

### Clase SyntheticsBrowser
<a name="CloudWatch_Synthetics_Library_Python_SyntheticsBrowser"></a>

**nota**  
Chrome es el único navegador compatible con `SyntheticsBrowser`.

Cuando se crea una instancia de navegador mediante una llamada a `synthetics_webdriver.Chrome()`, la instancia del navegador devuelta es del tipo `SyntheticsBrowser`. La clase ` SyntheticsBrowser` hereda la clase WebDriver y proporciona acceso a todos los métodos expuestos por [WebDriver](https://www.selenium.dev/documentation/webdriver/). Controla el ChromeDriver y habilita el script del canario para manejar el navegador, lo que permite al WebDriver Selenium trabajar con Synthetics.

**nota**  
Synthetics anula el método [quit](https://www.selenium.dev/selenium/docs/api/py/selenium_webdriver_firefox/selenium.webdriver.firefox.webdriver.html) de WebDriver para no realizar ninguna acción. No debe preocuparse por cerrar el navegador, ya que Synthetics se encarga de ello.

Además de los métodos estándar de Selenium, también proporciona los siguientes métodos. 

**Topics**
+ [set\$1viewport\$1size(ancho, alto)](#CloudWatch_Synthetics_Library_set_viewport_size)
+ [save\$1screenshot(nombre del archivo, sufijo)](#CloudWatch_Synthetics_Library_save_screenshot)

#### set\$1viewport\$1size(ancho, alto)
<a name="CloudWatch_Synthetics_Library_set_viewport_size"></a>

Establece la ventana gráfica del navegador. Ejemplo:

```
browser.set_viewport_size(1920, 1080)
```

#### save\$1screenshot(nombre del archivo, sufijo)
<a name="CloudWatch_Synthetics_Library_save_screenshot"></a>

Guarda capturas de pantalla en el directorio de `/tmp`. Las capturas de pantalla se cargan desde allí a la carpeta de artefactos de valores controlados en el bucket de S3.

*filename* es el nombre del archivo de la captura de pantalla, y *suffix* es una cadena opcional que se utilizará para nombrar la captura de pantalla.

Ejemplo:

```
browser.save_screenshot('loaded.png', 'page1')
```

### Clase SyntheticsWebDriver
<a name="CloudWatch_Synthetics_Library_Python_SyntheticsWebDriver"></a>

Para utilizar esta clase, utilice lo siguiente en su script:

```
from aws_synthetics.selenium import synthetics_webdriver
```

**Topics**
+ [add\$1execution\$1error(errorMessage, ex);](#CloudWatch_Synthetics_Library_Python_addExecutionError)
+ [add\$1user\$1agent(user\$1agent\$1str)](#CloudWatch_Synthetics_Library_add_user_agent)
+ [execute\$1step(step\$1name, function\$1to\$1execute)](#CloudWatch_Synthetics_Library_Python_execute_step)
+ [get\$1http\$1response(url)](#CloudWatch_Synthetics_Library_Python_get_http_response)
+ [Chrome()](#CloudWatch_Synthetics_Library_Python_Chrome)

#### add\$1execution\$1error(errorMessage, ex);
<a name="CloudWatch_Synthetics_Library_Python_addExecutionError"></a>

`errorMessage` describe el error y `ex` es la excepción que se ha encontrado

`add_execution_error` puede usarse para establecer errores de ejecución para el valor controlado. Se produce un error en el valor controlado sin interrumpir la ejecución del script. Tampoco afecta a las métricas de `successPercent`.

Debe realizar un seguimiento de los errores como errores de ejecución sólo si no son importantes para indicar el éxito o el error del script valor controlado.

A continuación, se muestra un ejemplo del uso de un `add_execution_error`. Está supervisando la disponibilidad de su punto de conexión y tomando capturas de pantalla después de que la página se haya cargado. Debido a que el hecho de no tomar una captura de pantalla no determina la disponibilidad del punto de enlace, puede detectar cualquier error que encuentre al tomar capturas de pantalla y agregarlos como errores de ejecución. Las métricas de disponibilidad seguirán indicando que el punto de conexión está activo y en ejecución, pero el estado del valor controlado se marcará como fallido. El siguiente bloque de código de muestra detecta dicho error y lo agrega como un error de ejecución.

```
try:
    browser.save_screenshot("loaded.png")  
except Exception as ex:
   self.add_execution_error("Unable to take screenshot", ex)
```

#### add\$1user\$1agent(user\$1agent\$1str)
<a name="CloudWatch_Synthetics_Library_add_user_agent"></a>

Añade el valor de `user_agent_str` a la cabecera del agente de usuario del navegador. Debe asignar `user_agent_str` antes de crear la instancia del navegador.

Ejemplo:

```
await synthetics_webdriver.add_user_agent('MyApp-1.0')
```

`add_user_agent` debe usarse dentro de una función `async`.

#### execute\$1step(step\$1name, function\$1to\$1execute)
<a name="CloudWatch_Synthetics_Library_Python_execute_step"></a>

Procesa una función. También hace lo siguiente:
+ Registra que el paso se ha iniciado.
+ Toma una captura de pantalla denominada `<stepName>-starting`.
+ Inicia un temporizador.
+ Ejecuta la función proporcionada.
+ Si la función devuelve resultados normalmente, cuenta como superada. Si la función falla, cuenta como error.
+ Finaliza el temporizador.
+ Registra si el paso se ha superado o no.
+ Toma una captura de pantalla denominada `<stepName>-succeeded` o ` <stepName>-failed`.
+ Emite la métrica `stepName` `SuccessPercent`, 100 para superado o 0 para no superado.
+ Emite la métrica `stepName` `Duration`, con un valor basado en las horas de inicio y de finalización del paso.
+ Por último, devuelve el mismo resultado que `functionToExecute` o vuelve a arrojar el mismo error que `functionToExecute`.

Ejemplo:

```
from selenium.webdriver.common.by import By

def custom_actions():
        #verify contains
        browser.find_element(By.XPATH, "//*[@id=\"id_1\"][contains(text(),'login')]")
        #click a button
        browser.find_element(By.XPATH, '//*[@id="submit"]/a').click()

    await synthetics_webdriver.execute_step("verify_click", custom_actions)
```

#### get\$1http\$1response(url)
<a name="CloudWatch_Synthetics_Library_Python_get_http_response"></a>

Realiza una solicitud HTTP a la URL proporcionada y devuelve el código de respuesta de la solicitud HTTP. Si se ha producido una excepción durante la solicitud HTTP, en su lugar se devuelve una cadena con el valor “error”.

Ejemplo:

```
response_code = syn_webdriver.get_http_response(url)
if not response_code or response_code == "error" or response_code < 200 or response_code > 299:
    raise Exception("Failed to load page!")
```

#### Chrome()
<a name="CloudWatch_Synthetics_Library_Python_Chrome"></a>

Lanza una instancia del navegador Chromium y muestra la instancia creada del navegador.

Ejemplo:

```
browser = synthetics_webdriver.Chrome()
browser.get("https://example.com/)
```

Para lanzar un navegador en modo de incógnito, utilice lo siguiente:

```
add_argument('——incognito')
```

Para agregar la configuración del proxy, utilice lo siguiente:

```
add_argument('--proxy-server=%s' % PROXY)
```

Ejemplo:

```
from selenium.webdriver.chrome.options import Options
chrome_options = Options()
chrome_options.add_argument("——incognito")
browser = syn_webdriver.Chrome(chrome_options=chrome_options)
```