appium-espresso-driver
Version:
Espresso integration for Appium
422 lines • 19.5 kB
JavaScript
import { JWProxy, errors } from 'appium/driver.js';
import { sleep, waitForCondition } from 'asyncbox';
import path from 'node:path';
import { fileURLToPath } from 'node:url';
import { fs, node, util, timing } from 'appium/support.js';
import { getPackageInfoSync, getPackageInfo, isPlainObject } from '../../utils/index.js';
import { ServerBuilder, buildServerSigningConfig } from './builder.js';
import { ESPRESSO_SERVER_LAUNCH_TIMEOUT_MS, TARGET_PACKAGE_CONTAINER, TEST_APK_PKG, } from './constants.js';
import axios from 'axios';
import * as semver from 'semver';
class EspressoProxy extends JWProxy {
instrumentationState;
async proxyCommand(url, method, body = null) {
const { crashed, exited } = this.instrumentationState;
if (exited) {
throw new errors.InvalidContextError(`'${method} ${url}' cannot be proxied to Espresso server because ` +
`the instrumentation process has ${crashed ? 'crashed' : 'been unexpectedly terminated'}. ` +
`Check the Appium server log and the logcat output for more details`);
}
return await super.proxyCommand(url, method, body);
}
}
export class EspressoRunner {
host;
systemPort;
appPackage;
adb;
tmpDir;
forceEspressoRebuild;
devicePort;
jwproxy;
proxyReqRes;
proxyCommand;
modServerPath;
showGradleLog;
espressoBuildConfig;
serverLaunchTimeout;
androidInstallTimeout;
disableSuppressAccessibilityService;
signingConfig;
instProcess = null;
log;
constructor(log, opts) {
this.adb = requireOption(opts, 'adb');
this.tmpDir = requireOption(opts, 'tmpDir');
this.host = requireOption(opts, 'host');
this.systemPort = requireOption(opts, 'systemPort');
this.devicePort = requireOption(opts, 'devicePort');
this.appPackage = requireOption(opts, 'appPackage');
this.forceEspressoRebuild = requireOption(opts, 'forceEspressoRebuild');
this.log = log;
const proxyOpts = {
log,
server: this.host,
port: this.systemPort,
keepAlive: true,
};
if (opts.reqBasePath) {
proxyOpts.reqBasePath = opts.reqBasePath;
}
this.jwproxy = new EspressoProxy(proxyOpts);
this.proxyReqRes = this.jwproxy.proxyReqRes.bind(this.jwproxy);
this.proxyCommand = this.jwproxy.command.bind(this.jwproxy);
this.jwproxy.instrumentationState = {
exited: false,
crashed: false,
};
const { manifestPayload } = getPackageInfoSync();
const modServerName = fs.sanitizeName(`${TEST_APK_PKG}_${manifestPayload.version}_${this.appPackage}_${this.adb.curDeviceId}.apk`, { replacement: '-' });
this.modServerPath = path.resolve(this.tmpDir, modServerName);
this.showGradleLog = opts.showGradleLog;
this.espressoBuildConfig = opts.espressoBuildConfig;
this.serverLaunchTimeout = opts.serverLaunchTimeout || ESPRESSO_SERVER_LAUNCH_TIMEOUT_MS;
this.androidInstallTimeout = opts.androidInstallTimeout;
this.disableSuppressAccessibilityService = opts.disableSuppressAccessibilityService;
// Espresso Server app needs to be signed with same keyStore as appPackage
if (opts.useKeystore &&
opts.keystorePath &&
opts.keystorePassword &&
opts.keyAlias &&
opts.keyPassword) {
this.signingConfig = buildServerSigningConfig({
keystoreFile: opts.keystorePath,
keystorePassword: opts.keystorePassword,
keyAlias: opts.keyAlias,
keyPassword: opts.keyPassword,
});
}
else {
this.signingConfig = null;
}
}
async isAppPackageChanged() {
if (!(await this.adb.fileExists(TARGET_PACKAGE_CONTAINER))) {
this.log.debug('The previous target application package is unknown');
return true;
}
const previousAppPackage = (await this.adb.shell(['cat', TARGET_PACKAGE_CONTAINER])).trim();
this.log.debug(`The previous target application package was '${previousAppPackage}'. ` +
`The current package is '${this.appPackage}'`);
return previousAppPackage !== this.appPackage;
}
/**
* Installs Espresso server apk on to the device or emulator.
* Each adb command uses default timeout by them.
*/
async installServer() {
const appState = await this.adb.getApplicationInstallState(this.modServerPath, TEST_APK_PKG);
const shouldUninstallApp = [
this.adb.APP_INSTALL_STATE.OLDER_VERSION_INSTALLED,
this.adb.APP_INSTALL_STATE.NEWER_VERSION_INSTALLED,
].includes(appState);
const shouldInstallApp = shouldUninstallApp || [this.adb.APP_INSTALL_STATE.NOT_INSTALLED].includes(appState);
if (shouldUninstallApp) {
this.log.info(`Uninstalling Espresso Test Server apk from the target device (pkg: '${TEST_APK_PKG}')`);
try {
await this.adb.uninstallApk(TEST_APK_PKG);
}
catch (err) {
this.log.warn(`Error uninstalling '${TEST_APK_PKG}': ${err.message}`);
}
}
if (shouldInstallApp) {
this.log.info(`Installing Espresso Test Server apk from the target device (path: '${this.modServerPath}')`);
try {
await this.adb.install(this.modServerPath, {
replace: false,
timeout: this.androidInstallTimeout,
});
this.log.info(`Installed Espresso Test Server apk '${this.modServerPath}' (pkg: '${TEST_APK_PKG}')`);
}
catch (err) {
throw this.log.errorWithException(`Cannot install '${this.modServerPath}' because of '${err.message}'`);
}
}
}
async installTestApk() {
let rebuild = this.forceEspressoRebuild;
if (rebuild) {
this.log.debug(`'forceEspressoRebuild' capability is enabled`);
}
else if (await this.isAppPackageChanged()) {
this.log.info(`Forcing Espresso server rebuild because of changed application package`);
rebuild = true;
}
if (rebuild && (await fs.exists(this.modServerPath))) {
this.log.debug(`Deleting the obsolete Espresso server package '${this.modServerPath}'`);
await fs.unlink(this.modServerPath);
}
if (!(await fs.exists(this.modServerPath))) {
await this.buildNewModServer();
}
const wasSigned = await this.adb.checkApkCert(this.modServerPath);
if (!wasSigned) {
await this.adb.sign(this.modServerPath);
}
if ((rebuild || !wasSigned) && (await this.adb.uninstallApk(TEST_APK_PKG))) {
this.log.info('Uninstalled the obsolete Espresso server package from the device under test');
}
await this.installServer();
}
async buildNewModServer() {
let buildConfiguration = {};
if (this.espressoBuildConfig) {
let buildConfigurationStr;
if (await fs.exists(this.espressoBuildConfig)) {
this.log.info(`Loading the build configuration from '${this.espressoBuildConfig}'`);
buildConfigurationStr = await fs.readFile(this.espressoBuildConfig, 'utf8');
}
else {
this.log.info(`Loading the build configuration from 'espressoBuildConfig' capability`);
buildConfigurationStr = this.espressoBuildConfig;
}
try {
buildConfiguration = JSON.parse(buildConfigurationStr);
}
catch (e) {
this.log.error('Cannot parse the build configuration JSON', e);
throw e;
}
}
const dirName = fs.sanitizeName(`espresso-server-${this.adb.curDeviceId}`, {
replacement: '-',
});
const serverPath = path.resolve(this.tmpDir, dirName);
this.log.info(`Building espresso server in '${serverPath}'`);
this.log.debug(`The build folder root could be customized by changing the 'tmpDir' capability`);
await fs.rimraf(serverPath);
await fs.mkdirp(serverPath);
this.log.debug(`Copying espresso server template from ('${getTestServerRoot()}' to '${serverPath}')`);
await copyGradleProjectRecursively(getTestServerRoot(), serverPath);
this.log.debug('Bulding espresso server');
await new ServerBuilder(this.log, {
serverPath,
buildConfiguration,
showGradleLog: this.showGradleLog,
testAppPackage: this.appPackage,
signingConfig: this.signingConfig,
}).build();
const apkPath = path.resolve(serverPath, 'app', 'build', 'outputs', 'apk', 'androidTest', 'debug', 'app-debug-androidTest.apk');
this.log.debug(`Copying built apk from '${apkPath}' to '${this.modServerPath}'`);
await fs.copyFile(apkPath, this.modServerPath);
}
async startSession(caps) {
await this.cleanupSessionLeftovers();
const cmd = [
'shell',
'am',
'instrument',
'-w',
'-e',
'debug',
String(process.env.ESPRESSO_JAVA_DEBUG === 'true'),
'-e',
'disableAnalytics',
'true', // To avoid unexpected error by google analytics
];
if (typeof this.disableSuppressAccessibilityService === 'boolean') {
cmd.push('-e', 'DISABLE_SUPPRESS_ACCESSIBILITY_SERVICES', String(this.disableSuppressAccessibilityService));
}
cmd.push(`${TEST_APK_PKG}/androidx.test.runner.AndroidJUnitRunner`);
const { manifestPayload } = await getPackageInfo();
this.log.info(`Starting Espresso Server v${manifestPayload.version} with cmd: adb ${cmd.join(' ')}`);
let hasSocketError = false;
// start the instrumentation process
this.jwproxy.instrumentationState = {
exited: false,
crashed: false,
};
this.instProcess = this.adb.createSubProcess(cmd);
this.instProcess.on('exit', (code, signal) => {
this.log.info(`Instrumentation process exited with code ${code} from signal ${signal}`);
this.jwproxy.instrumentationState.exited = true;
});
this.instProcess.on('output', (stdout, stderr) => {
const line = stdout || stderr;
if (!line.trim()) {
// Do not print empty lines into the system log
return;
}
this.log.debug(`[Instrumentation] ${line.trim()}`);
// A 'SocketException' indicates that we couldn't connect to the Espresso server,
// because the INTERNET permission is not set
if (line.toLowerCase().includes('java.net.socketexception')) {
hasSocketError = true;
}
else if (line.includes('Process crashed')) {
this.jwproxy.instrumentationState.crashed = true;
}
});
const timer = new timing.Timer().start();
await this.instProcess.start(0);
this.log.info(`Waiting up to ${this.serverLaunchTimeout}ms for Espresso server to be online`);
try {
await waitForCondition(async () => {
if (hasSocketError) {
throw this.log.errorWithException(`Espresso server has failed to start due to an unexpected exception. ` +
`Make sure the 'INTERNET' permission is requested in the Android manifest of your ` +
`application under test (<uses-permission android:name="android.permission.INTERNET" />)`);
}
else if (this.jwproxy.instrumentationState.exited) {
throw this.log.errorWithException(`Espresso server process has been unexpectedly terminated. ` +
`Check the Appium server log and the logcat output for more details`);
}
let serverStatus;
try {
serverStatus = (await this.jwproxy.command('/status', 'GET'));
}
catch {
return false;
}
return await this._verifyServerStatus(manifestPayload.version, serverStatus);
}, {
waitMs: this.serverLaunchTimeout,
intervalMs: 500,
});
}
catch (e) {
if (/Condition unmet/.test(e.message)) {
throw this.log.errorWithException(`Timed out waiting for Espresso server to be ` +
`online within ${this.serverLaunchTimeout}ms. The timeout value could be ` +
`customized using 'espressoServerLaunchTimeout' capability`);
}
throw e;
}
this.log.info(`Espresso server is online. ` +
`The initialization process took ${timer.getDuration().asMilliSeconds.toFixed(0)}ms`);
this.log.info('Starting the session');
await this.jwproxy.command('/session', 'POST', {
capabilities: {
firstMatch: [caps],
alwaysMatch: {},
},
});
await this.recordTargetAppPackage();
}
async deleteSession() {
this.log.debug('Deleting Espresso server session');
// rely on jwproxy's intelligence to know what we're talking about and
// delete the current session
try {
await this.jwproxy.command('/', 'DELETE');
}
catch (err) {
this.log.warn(`Did not get confirmation Espresso deleteSession worked; ` + `Error was: ${err}`);
}
if (this.instProcess?.isRunning) {
await this.instProcess.stop();
}
}
async cleanupSessionLeftovers() {
this.log.debug('Performing cleanup of automation leftovers');
try {
const { value } = (await axios({
url: `http://${this.host}:${this.systemPort}/sessions`,
timeout: 500,
})).data;
const activeSessionIds = value.map((sess) => sess.id);
if (activeSessionIds.length) {
this.log.debug(`The following obsolete sessions are still running: ${JSON.stringify(activeSessionIds)}`);
this.log.debug('Cleaning up the obsolete sessions');
await Promise.all(activeSessionIds.map((id) => axios({
url: `http://${this.host}:${this.systemPort}/session/${id}`,
method: 'DELETE',
})));
// Let all sessions to be properly terminated before continuing
await sleep(1000);
}
else {
this.log.debug('No obsolete sessions have been detected');
}
}
catch (e) {
this.log.debug(`No obsolete sessions have been detected (${e.message})`);
}
}
async recordTargetAppPackage() {
await this.adb.shell([`echo "${this.appPackage}" > "${TARGET_PACKAGE_CONTAINER}"`]);
this.log.info(`Recorded the target application package '${this.appPackage}' to ${TARGET_PACKAGE_CONTAINER}`);
}
async _verifyServerStatus(driverVersion, serverStatus) {
if (!isPlainObject(serverStatus) || !isPlainObject(serverStatus.build)) {
throw this.log.errorWithException(`The Espresso server version integrated with the application under test is not compatible ` +
`with the current driver version '${driverVersion}'.`);
}
const { build: { version: serverVersion, packageName: serverPackageName }, } = serverStatus;
const appLabel = serverPackageName
? `'${serverPackageName}' application`
: 'application under test';
const parsedServerVersion = semver.coerce(serverVersion);
const parsedDriverVersion = semver.coerce(driverVersion);
if (parsedServerVersion && parsedDriverVersion) {
if (parsedServerVersion.major !== parsedDriverVersion.major) {
throw this.log.errorWithException(`The Espresso server version '${serverVersion}' integrated with the ${appLabel} is not compatible ` +
`with the current driver version '${driverVersion}'.`);
}
else if (parsedServerVersion.minor < parsedDriverVersion.minor) {
this.log.warn(`The Espresso server version integrated with the ${appLabel} might not be compatible ` +
`with the current driver version (${serverVersion} < ${driverVersion})'.`);
}
}
else {
const warnMessage = parsedServerVersion
? `The Espresso driver version '${driverVersion}' ` +
`cannot be parsed. It might be incompatible with the current server '${serverVersion}' ` +
`integrated with the ${appLabel}.`
: `The Espresso server version '${serverVersion}' integrated with the ${appLabel} ` +
`cannot be parsed. It might be incompatible with the current driver ` +
`version '${driverVersion}'.`;
this.log.warn(warnMessage);
}
if (this.appPackage && serverPackageName && this.appPackage !== serverPackageName) {
throw this.log.errorWithException(`The Espresso server that is listening on the device under tests is built for a different ` +
`application package (${serverPackageName} !== ${this.appPackage}).`);
}
return true;
}
}
function requireOption(opts, key) {
if (!util.hasValue(opts[key])) {
throw new Error(`Option '${key}' is required!`);
}
return opts[key];
}
const MODULE_NAME = 'appium-espresso-driver';
const FILENAME = fileURLToPath(import.meta.url);
let testServerRoot;
/**
* Recursively copy all files except build directories contents
* @param sourceBaseDir directory to copy files from
* @param targetBaseDir directory to copy files to
*/
export async function copyGradleProjectRecursively(sourceBaseDir, targetBaseDir) {
// @ts-ignore it is ok to have the async callback
await fs.walkDir(sourceBaseDir, true, async (itemPath, isDirectory) => {
const relativePath = path.relative(sourceBaseDir, itemPath);
const targetPath = path.resolve(targetBaseDir, relativePath);
const isInGradleBuildDir = `${path.sep}${itemPath}`.includes(`${path.sep}build${path.sep}`);
if (isInGradleBuildDir) {
return false;
}
if (isDirectory) {
await fs.mkdirp(targetPath);
}
else {
await fs.copyFile(itemPath, targetPath);
}
return false;
});
}
/** Root path of the bundled Espresso server Gradle project. */
function getTestServerRoot() {
if (testServerRoot === undefined) {
const moduleRoot = node.getModuleRootSync(MODULE_NAME, FILENAME);
if (!moduleRoot) {
throw new Error(`Cannot find the root folder of the ${MODULE_NAME} Node.js module`);
}
testServerRoot = path.join(moduleRoot, 'espresso-server');
}
return testServerRoot;
}
//# sourceMappingURL=runner.js.map