Capítulo 1: Instalación y Configuración del Entorno Appium

18 de enero de 2025 Por: Artiko

appiuminstalaciónnodejsandroid-sdkjdkconfiguraciónambiente

Capítulo 1: Instalación y Configuración del Entorno Appium

Este capítulo te guiará paso a paso en la instalación completa del entorno de Appium, asegurando que cada componente esté correctamente configurado para trabajar con dispositivos Android físicos conectados por USB.

📋 Requisitos del Sistema

Hardware Mínimo

RAM: 8 GB (16 GB recomendado)
Disco: 10 GB libres para SDK y herramientas
CPU: Procesador multi-core moderno
USB: Puerto USB 2.0 o superior

Sistemas Operativos Soportados

Windows: 10/11 (64-bit)
macOS: 10.15 (Catalina) o superior
Linux: Ubuntu 20.04+, Debian 10+, Fedora 33+

Versiones de Software Requeridas

const requirements = {
  nodejs: "18.0.0+",  // LTS recomendado
  npm: "8.0.0+",
  java: "11+",        // JDK 11, 17 o 21
  androidApi: "21+",  // Android 5.0 Lollipop
  appium: "2.0+",     // Última versión estable
  python: "3.8+"      // Si usas Python para tests
};

🔧 Paso 1: Instalación de Node.js y npm

Windows

Descargar Node.js:

# Opción 1: Descargar desde https://nodejs.org/
# Elegir versión LTS (Long Term Support)

# Opción 2: Usar Chocolatey
choco install nodejs-lts

Verificar instalación:

node --version
# Output esperado: v18.x.x o superior

npm --version
# Output esperado: 8.x.x o superior

macOS

# Opción 1: Usar Homebrew
brew install node@18

# Opción 2: Usar nvm (Node Version Manager)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install 18
nvm use 18
nvm alias default 18

# Verificar
node --version && npm --version

Linux (Ubuntu/Debian)

# Actualizar repositorios
sudo apt update

# Instalar Node.js 18.x
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt-get install -y nodejs

# Verificar instalación
node --version
npm --version

☕ Paso 2: Instalación de Java JDK

Windows

# Opción 1: Descargar Oracle JDK o OpenJDK
# https://www.oracle.com/java/technologies/downloads/
# https://adoptium.net/

# Opción 2: Usar Chocolatey
choco install openjdk11

# Configurar JAVA_HOME
setx JAVA_HOME "C:\Program Files\OpenJDK\jdk-11"
setx PATH "%PATH%;%JAVA_HOME%\bin"

# Verificar
java -version
javac -version

macOS

# Instalar con Homebrew
brew install openjdk@11

# Configurar JAVA_HOME en ~/.zshrc o ~/.bash_profile
echo 'export JAVA_HOME=$(/usr/libexec/java_home -v 11)' >> ~/.zshrc
echo 'export PATH=$JAVA_HOME/bin:$PATH' >> ~/.zshrc
source ~/.zshrc

# Verificar
java -version

Linux

# Ubuntu/Debian
sudo apt update
sudo apt install openjdk-11-jdk

# Configurar JAVA_HOME
echo 'export JAVA_HOME=/usr/lib/jvm/java-11-openjdk-amd64' >> ~/.bashrc
echo 'export PATH=$JAVA_HOME/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

# Verificar
java -version

📱 Paso 3: Instalación de Android SDK

Opción A: Android Studio (Recomendado para principiantes)

Descargar Android Studio:
- Visitar: https://developer.android.com/studio
- Descargar versión para tu OS
- Instalar con configuración por defecto
Configurar SDK Manager:

// En Android Studio:
// Tools → SDK Manager → SDK Platforms
✓ Android 13.0 (API 33)
✓ Android 12.0 (API 31)
✓ Android 11.0 (API 30)

// SDK Tools
✓ Android SDK Build-Tools
✓ Android SDK Platform-Tools
✓ Android SDK Command-line Tools
✓ Android Emulator (opcional)
✓ Intel x86 Emulator Accelerator (HAXM)

Opción B: Command Line Tools (Avanzado)

# Descargar Command Line Tools
# https://developer.android.com/studio#command-line-tools-only

# Linux/macOS
mkdir -p ~/Android/sdk
cd ~/Android/sdk
wget https://dl.google.com/android/repository/commandlinetools-linux-9477386_latest.zip
unzip commandlinetools-*.zip
mkdir -p cmdline-tools/latest
mv cmdline-tools/* cmdline-tools/latest/ 2>/dev/null || true

# Instalar componentes necesarios
./cmdline-tools/latest/bin/sdkmanager --update
./cmdline-tools/latest/bin/sdkmanager "platform-tools" "platforms;android-33" "build-tools;33.0.0"

Configurar Variables de Entorno

Windows

# Variables de sistema
setx ANDROID_HOME "%LOCALAPPDATA%\Android\Sdk"
setx PATH "%PATH%;%ANDROID_HOME%\platform-tools;%ANDROID_HOME%\tools;%ANDROID_HOME%\tools\bin"

# Reiniciar terminal y verificar
echo %ANDROID_HOME%
adb version

macOS/Linux

# Agregar a ~/.bashrc, ~/.zshrc o ~/.profile
export ANDROID_HOME=$HOME/Android/Sdk
export PATH=$PATH:$ANDROID_HOME/platform-tools
export PATH=$PATH:$ANDROID_HOME/tools
export PATH=$PATH:$ANDROID_HOME/tools/bin
export PATH=$PATH:$ANDROID_HOME/emulator

# Recargar configuración
source ~/.bashrc  # o source ~/.zshrc

# Verificar
echo $ANDROID_HOME
adb version

🚀 Paso 4: Instalación de Appium Server

Instalación Global con npm

# Instalar Appium globalmente
npm install -g appium@latest

# Verificar instalación
appium --version
# Output esperado: 2.x.x

# Ver ayuda
appium --help

Instalación del Driver UiAutomator2

# Instalar driver para Android
appium driver install uiautomator2

# Verificar drivers instalados
appium driver list --installed

# Output esperado:
# ✔ Listing installed drivers
# - [email protected] [installed (npm)]

Instalación de Drivers Adicionales (Opcional)

# Espresso Driver (para white-box testing)
appium driver install espresso

# XCUITest Driver (para iOS)
appium driver install xcuitest

# Windows Driver (para apps Windows)
appium driver install windows

# Listar todos los drivers disponibles
appium driver list

🏥 Paso 5: Appium Doctor - Validación del Entorno

Instalación de Appium Doctor

# Instalar globalmente
npm install -g @appium/doctor

# Ejecutar validación para Android
appium-doctor --android

# Output esperado (todos deben estar en verde ✓):
# info AppiumDoctor Appium Doctor v.2.x.x
# info AppiumDoctor ### Diagnostic for necessary dependencies starting ###
# ✓ Node.js is installed
# ✓ JAVA_HOME is set
# ✓ ANDROID_HOME is set
# ✓ adb exists
# ✓ android exists
# ✓ Bin directory of $JAVA_HOME is in PATH

Solución de Problemas Comunes

// Problema: ANDROID_HOME not set
// Solución:
if (os === 'windows') {
  // Panel de Control → Sistema → Configuración avanzada
  // Variables de entorno → Nueva variable de sistema
  // ANDROID_HOME = C:\Users\[usuario]\AppData\Local\Android\Sdk
} else {
  // Agregar a ~/.bashrc o ~/.zshrc
  // export ANDROID_HOME=$HOME/Android/Sdk
}

// Problema: adb not found
// Solución: Agregar platform-tools al PATH
const platformToolsPath = `${ANDROID_HOME}/platform-tools`;

// Problema: JAVA_HOME incorrect
// Verificar con:
// java -version
// which java (Linux/macOS)
// where java (Windows)

🛠️ Paso 6: Herramientas Adicionales

Appium Inspector (GUI para debugging)

# Descargar desde:
# https://github.com/appium/appium-inspector/releases

# O instalar via npm (versión web)
npm install -g appium-inspector

Chrome y ChromeDriver

# Verificar versión de Chrome en el dispositivo
adb shell dumpsys package com.android.chrome | grep versionName

# Appium descarga automáticamente el ChromeDriver correcto
# O puedes especificar manualmente:
appium --chromedriver-executable /path/to/chromedriver

Python Client (si usas Python)

# Crear entorno virtual
python -m venv appium-env
source appium-env/bin/activate  # Linux/macOS
# o
appium-env\Scripts\activate  # Windows

# Instalar Appium-Python-Client
pip install Appium-Python-Client
pip install pytest  # Framework de testing

Java Client (si usas Java)

<!-- Maven: pom.xml -->
<dependency>
    <groupId>io.appium</groupId>
    <artifactId>java-client</artifactId>
    <version>9.1.0</version>
</dependency>

<!-- Gradle: build.gradle -->
dependencies {
    testImplementation 'io.appium:java-client:9.1.0'
    testImplementation 'org.testng:testng:7.8.0'
}

🔍 Paso 7: Verificación Completa del Entorno

Script de Verificación

// verify-setup.js
const { exec } = require('child_process');
const util = require('util');
const execPromise = util.promisify(exec);

async function verifySetup() {
  const checks = [
    { name: 'Node.js', command: 'node --version', minVersion: '18' },
    { name: 'npm', command: 'npm --version', minVersion: '8' },
    { name: 'Java', command: 'java -version', expected: 'version' },
    { name: 'JAVA_HOME', command: 'echo $JAVA_HOME', expected: '/jdk' },
    { name: 'Android SDK', command: 'echo $ANDROID_HOME', expected: '/Android' },
    { name: 'ADB', command: 'adb version', expected: 'Android Debug Bridge' },
    { name: 'Appium', command: 'appium --version', minVersion: '2' }
  ];

  console.log('🔍 Verificando entorno de Appium...\n');

  for (const check of checks) {
    try {
      const { stdout, stderr } = await execPromise(check.command);
      const output = stdout || stderr;
      
      if (check.minVersion) {
        const version = output.match(/\d+/)?.[0];
        if (parseInt(version) >= parseInt(check.minVersion)) {
          console.log(`✅ ${check.name}: ${output.trim()}`);
        } else {
          console.log(`❌ ${check.name}: Versión ${version} < ${check.minVersion}`);
        }
      } else if (check.expected && output.includes(check.expected)) {
        console.log(`✅ ${check.name}: ${output.trim()}`);
      } else {
        console.log(`✅ ${check.name}: ${output.trim()}`);
      }
    } catch (error) {
      console.log(`❌ ${check.name}: No instalado o no configurado`);
    }
  }
}

verifySetup();

Ejecutar verificación:

node verify-setup.js

🚦 Paso 8: Primer Arranque de Appium

Iniciar Servidor Básico

# Arranque simple
appium

# Output esperado:
# [Appium] Welcome to Appium v2.x.x
# [Appium] Attempting to load driver uiautomator2...
# [Appium] Appium REST http interface listener started on http://0.0.0.0:4723
# [Appium] You can provide the following URLs in your client code:
# [Appium] http://127.0.0.1:4723/ (only accessible from the same host)
# [Appium] http://192.168.1.x:4723/ (accessible from your network)

Arranque con Opciones Avanzadas

# Con logging detallado
appium --log-level debug

# En puerto específico
appium -p 4724

# Con archivo de configuración
appium --config ./appium.config.json

# Permitir CORS para Inspector
appium --allow-cors

# Con múltiples opciones
appium \
  --port 4723 \
  --log-level info \
  --log-timestamp \
  --local-timezone \
  --allow-cors

Archivo de Configuración (appium.config.json)

{
  "server": {
    "port": 4723,
    "host": "0.0.0.0",
    "keepAliveTimeout": 600,
    "logLevel": "info",
    "logTimestamp": true,
    "localTimezone": true,
    "logNoColors": false,
    "allowCors": true,
    "basePath": "/wd/hub"
  },
  "drivers": {
    "uiautomator2": {
      "androidInstallTimeout": 90000,
      "adbExecTimeout": 20000
    }
  }
}

📝 Checklist de Instalación

### ✅ Verificación Final

- [ ] Node.js 18+ instalado
- [ ] npm 8+ funcionando
- [ ] Java JDK 11+ configurado
- [ ] JAVA_HOME variable establecida
- [ ] Android SDK instalado
- [ ] ANDROID_HOME variable establecida
- [ ] ADB en PATH y funcionando
- [ ] Appium 2.x instalado globalmente
- [ ] UiAutomator2 driver instalado
- [ ] Appium Doctor sin errores
- [ ] Servidor Appium arranca correctamente
- [ ] Puerto 4723 disponible

🔧 Troubleshooting

Problema: Permission Denied (Linux/macOS)

# Error al instalar globalmente
sudo npm install -g appium --unsafe-perm=true --allow-root

# Mejor alternativa: cambiar directorio npm
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

Problema: Firewall Bloqueando Puerto

# Windows - Abrir puerto
netsh advfirewall firewall add rule name="Appium" dir=in action=allow protocol=TCP localport=4723

# Linux - Con ufw
sudo ufw allow 4723/tcp

# macOS - Verificar en Preferencias del Sistema → Seguridad

Problema: EACCES Error

# Cambiar permisos npm
sudo chown -R $(whoami) $(npm config get prefix)/{lib/node_modules,bin,share}

# O usar nvm para gestionar Node
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

🎯 Ejercicio Práctico

Crear Script de Inicio Personalizado

// start-appium.js
const { spawn } = require('child_process');
const path = require('path');

function startAppium() {
  console.log('🚀 Iniciando Appium Server...\n');
  
  const appium = spawn('appium', [
    '--port', '4723',
    '--log-level', 'info',
    '--log-timestamp',
    '--allow-cors'
  ], {
    stdio: 'inherit',
    shell: true
  });

  appium.on('error', (error) => {
    console.error('❌ Error iniciando Appium:', error);
  });

  appium.on('close', (code) => {
    console.log(`\n🛑 Appium cerrado con código: ${code}`);
  });

  // Capturar Ctrl+C
  process.on('SIGINT', () => {
    console.log('\n⏹️ Deteniendo Appium...');
    appium.kill();
    process.exit();
  });
}

// Verificar requisitos antes de iniciar
async function checkRequirements() {
  const { exec } = require('child_process');
  const util = require('util');
  const execPromise = util.promisify(exec);

  try {
    await execPromise('appium --version');
    await execPromise('adb version');
    return true;
  } catch (error) {
    console.error('❌ Requisitos no cumplidos. Ejecuta appium-doctor');
    return false;
  }
}

// Main
(async () => {
  if (await checkRequirements()) {
    startAppium();
  }
})();

📚 Resumen

Has completado exitosamente la instalación del entorno de Appium. Ahora tienes:

✅ Node.js y npm configurados
✅ Java JDK instalado y JAVA_HOME configurado
✅ Android SDK con herramientas necesarias
✅ Variables de entorno correctamente establecidas
✅ Appium Server 2.x instalado
✅ UiAutomator2 driver listo para Android
✅ Entorno validado con Appium Doctor

🚀 Próximo Paso

Con el entorno listo, el siguiente paso es preparar tu dispositivo Android para la automatización.

👉 Continuar con Capítulo 2: Preparación del Dispositivo Android

Tip: Guarda este capítulo como referencia. Si cambias de máquina o necesitas reinstalar, esta guía te ahorrará tiempo.