اعتبارًا من 27 آذار (مارس) 2025، ننصحك باستخدام android-latest-release بدلاً من aosp-main لإنشاء AOSP والمساهمة فيه. لمزيد من المعلومات، يُرجى الاطّلاع على التغييرات في AOSP.
أوامر shell للأجهزة
تنظيم صفحاتك في مجموعات
يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.
أثناء اختبار VTS، يتم استخدام أوامر shell لتنفيذ ملف ثنائي لاختبار على الجانب المستهدف، والحصول على السمات ومتغيرات البيئة ومعلومات النظام أو ضبطها، وبدء إطار عمل Android أو إيقافه. يمكنك تنفيذ أوامر ملف شل جهاز VTS
باستخدام الأمر adb shell أو برنامج تشغيل ملف شل VTS
الذي يعمل على الجهاز (إجراء يُنصح به).
استخدام أداة ADB shell
إنّ الاختبارات التي تتطلّب إغلاق منفذ USB أو إعادة تشغيل الجهاز أثناء
الاختبار يجب أن تستخدم ADB shell لأنّ برنامج تشغيل shell في VTS غير متاح بدون
اتصال USB مستمر. يمكنك استدعاء shell ADB من عنصر
AndroidDevice في نص اختبار Python. أمثلة:
- الحصول على عنصر جهاز Android:
self.device = self.android_devices[0]
- أدخِل أمرًا واحدًا لوحدة التحكّم في البرامج:
result = self.device.adb.shell(‘ls')
استخدام برنامج تشغيل shell في VTS
سائق shell في VTS هو ملف ثنائي للوكيل يتم تشغيله على الجهاز وتنفيذه
أوامر shell. يستخدم VTS تلقائيًا برنامج تشغيل shell إذا كان البرنامج قيد التشغيل
على الجهاز لأنّ هذه الطريقة تتميز بوقت استجابة أقل من استخدام الأمر adb
shell.
الشكل 1: برنامج تشغيل shell في VTS
يتيح إطار عمل VTS اختبار الأجهزة المتعددة حيث يتم تمثيل كل جهاز Android
ككائن AndroidDevice في أداة التشغيل الأساسية. يُرسِل إطار عمل VTS
الثنائيات الخاصة ببرنامج تشغيل VTS shell ووكيل VTS تلقائيًا إلى كل جهاز Android ويُنشئ اتصالات بروتوكول التحكم في الإرسال (TCP) مع وكلاء VTS على هذه الأجهزة.
لتنفيذ أمر shell، يُجري النص البرمجي Python من جهة المضيف دالة
استدعاء للكائن ShellMirror داخل كائن AndroidDevice. يُجمِّع عنصر ShellMirror
نصوص أوامر shell في رسالة
protobuf
ويرسلها (عبر قناة TCP) إلى وكيل VTS على
جهاز Android. بعد ذلك، يعيد الوكيل الذي يعمل على الجهاز توجيه الأمر المُرسَل إلى shell إلى ملف تعريف قاعدة بيانات VTS
driver عبر مقبس Unix.
عندما يتلقّى برنامج تشغيل واجهة سطر أوامر VTS أمرًا من واجهة سطر الأوامر، ينفّذ الأمر
من خلال nohup في
واجهة سطر أوامر الجهاز لمنع تعليقه. بعد ذلك، يتم retrievingاسترداد Stdout وstderr ورمز الإرجاع من nohup وإرساله مرة أخرى إلى موظّف دعم VTS. أخيرًا، يردّ موظّف الدعم
على المضيف من خلال تضمين نتائج الأوامر في رسالة
protobuf.
الإيجابيات
تشمل مزايا استخدام برنامج تشغيل shell في VTS بدلاً من adb
shell ما يلي:
- الموثوقية: يستخدم برنامج تشغيل shell في VTS
nohup لتنفيذ الأوامر على الإعداد التلقائي. بما أنّ اختبارات VTS هي
اختبارات HAL والنواة من المستوى الأدنى في الغالب، يضمن nohup عدم تعليق nohupأوامر shell أثناء التنفيذ.
- الأداء: على الرغم من أنّ الأمر
adb shell
يخزِّن مؤقتًا بعض النتائج (مثل إدراج الملفات في دليل)، إلا أنّه يستهلك موارد إضافية عند تنفيذ مهام مثل تنفيذ ملف ثنائي اختباري. يحافظ برنامج تشغيل VTS shell
على اتصال نشط طوال الاختبار، لذا فإنّ التكلفة الإضافية الوحيدة هي تواصل USB. في اختباراتنا، كان استخدام برنامج تشغيل shell في VTS لتنفيذ أمر يحتوي على
100 طلب إلى ملف gtest ثنائي فارغ أسرع بنسبة %20 تقريبًا من استخدام
adb shell، وكان الفرق الفعلي أكبر لأنّ ملف تواصل VTS shell
يتضمّن تسجيلًا مكثّفًا.
- الاحتفاظ بالحالة: يحافظ برنامج تشغيل shell في VTS على جلسة
محطة لكل اسم محطة (اسم المحطة التلقائي هو
default). لا تتوفّر متغيّرات البيئة التي تم ضبطها في جلسة وحدة طرفية واحدة إلا للأوامر اللاحقة في الجلسة نفسها.
- قابلة للتمديد: يتم لف اتصالات أوامر Shell بين إطار عمل VTS
وبرنامج تشغيل الجهاز في protobuf لتفعيل إمكانيات ملف protobuf في ما يتعلّق بالضغط والاتصال عن بُعد والتشفير وما إلى ذلك في المستقبل. تتوفّر أيضًا احتمالات أخرى لتحسين الأداء، بما في ذلك تحليل النتائج من جهة الجهاز
عندما تصبح النفقات العامة للتواصل أكبر من تحليل سلسلة النتائج.
السلبيات
تشمل عيوب استخدام برنامج تشغيل shell في VTS بدلاً من adb
shell ما يلي:
- الثنائيات الإضافية يجب دفع ملفات وكيل فحص الفيديو إلى
الجهاز وتنظيفها بعد تنفيذ الاختبار.
- تتطلّب هذه الميزة اتصالاً نشطًا. إذا انقطع اتصال بروتوكول النقل المتعدّد (TCP) بين العميل والوكيل أثناء الاختبار (بسبب انقطاع الاتصال عبر USB أو إيقاف المنفذ أو تعطُّل الجهاز أو غير ذلك) سواءً عن قصد أو عن غير قصد، لا يمكن إرسال أحد أوامر shell إلى وكيل فحص الأداء الظاهري. حتى في حال التبديل التلقائي إلى
adb shell، لن تكون نتيجة الأمر وحالته قبل انقطاع الاتصال معلومة.
أمثلة
أمثلة على استخدام أوامر shell في نص اختبار Python على جانب مضيف VTS:
- الحصول على عنصر جهاز Android:
self.device = self.android_devices[0]
- الحصول على عنصر shell للجهاز المحدّد:
self.shell = self.device.shell
- أدخِل أمرًا واحدًا لوحدة التحكّم في البرامج:
results = self.shell.Execute(‘ls')
- يمكنك إصدار قائمة بأوامر shell:
results = self.shell.Execute([‘cd /data/local/tmp', ‘ls'])
عنصر نتيجة الأمر
عنصر الإرجاع من تنفيذ أمر shell هو قاموس يحتوي على مفاتيح stdouts وstderrs وreturn_codes.
بغض النظر عمّا إذا كان يتم تقديم أمر shell كسلسلة واحدة أو قائمة
بسلاسل الأوامر، تكون كل قيمة من قاموس النتائج قائمة دائمًا.
للتحقّق من رمز الإرجاع لقائمة الأوامر، يجب أن يتحقّق النص البرمجي للاختبار من
الفهرس. مثال:
asserts.assertFalse(any(results[‘return_codes']), ‘some command failed.')
بدلاً من ذلك، يمكن للنص البرمجي التحقّق من كل فهرس أمر على حدة.
مثال:
asserts.assertEqual(results[‘return_codes'][0], 0, ‘first command failed')
asserts.assertEqual(results[‘return_codes'][1], 0, ‘second command failed')
يخضع كل من المحتوى وعيّنات التعليمات البرمجية في هذه الصفحة للتراخيص الموضحّة في ترخيص استخدام المحتوى. إنّ Java وOpenJDK هما علامتان تجاريتان مسجَّلتان لشركة Oracle و/أو الشركات التابعة لها.
تاريخ التعديل الأخير: 2025-07-27 (حسب التوقيت العالمي المتفَّق عليه)
[[["يسهُل فهم المحتوى.","easyToUnderstand","thumb-up"],["ساعَدني المحتوى في حلّ مشكلتي.","solvedMyProblem","thumb-up"],["غير ذلك","otherUp","thumb-up"]],[["لا يحتوي على المعلومات التي أحتاج إليها.","missingTheInformationINeed","thumb-down"],["الخطوات معقدة للغاية / كثيرة جدًا.","tooComplicatedTooManySteps","thumb-down"],["المحتوى قديم.","outOfDate","thumb-down"],["ثمة مشكلة في الترجمة.","translationIssue","thumb-down"],["مشكلة في العيّنات / التعليمات البرمجية","samplesCodeIssue","thumb-down"],["غير ذلك","otherDown","thumb-down"]],["تاريخ التعديل الأخير: 2025-07-27 (حسب التوقيت العالمي المتفَّق عليه)"],[],[],null,["# Device shell commands\n\nDuring VTS testing, shell commands are used to execute a target-side test\nbinary, to get/set properties, environment variables, and system information,\nand to start/stop the Android framework. You can execute VTS device shell\ncommands using the `adb shell` command or the VTS shell driver\nrunning on the device (recommended).\n\nUse ADB shell\n-------------\n\nTests that require shutting down the USB port or rebooting the device during\ntesting must use ADB shell as the VTS shell driver is unavailable without a\npersistent USB connection. You can invoke ADB shell from the\n`AndroidDevice` object in the Python test script. Examples:\n\n- Get an Android device object: \n\n ```\n self.device = self.android_devices[0]\n ```\n- Issue a single shell command: \n\n ```\n result = self.device.adb.shell(‘ls')\n ```\n\nUse the VTS shell driver\n------------------------\n\nThe VTS shell driver is an agent binary that runs on the device and executes\nshell commands. By default, VTS uses the shell driver if the driver is running\non device because this method has less latency than using the `adb\nshell` command.\n\n**Figure 1.** VTS shell driver.\n\nThe VTS framework supports multi-device testing where each Android device\nis represented as an AndroidDevice object in base runner. By default, VTS\nframework pushes VTS agent and VTS shell driver binaries to each Android device\nand establishes TCP connections to the VTS agents on those devices.\n\nTo execute a shell command, the host-side Python script makes a function\ncall to the ShellMirror object inside AndroidDevice object. The ShellMirror\nobject packs the shell command texts into a\n[protobuf](https://developers.google.com/protocol-buffers/)\nmessage and sends it (via the TCP channel) to the VTS agent on the Android\ndevice. The agent running on device then forwards the shell command to VTS shell\ndriver via the Unix socket.\n\nWhen the VTS shell driver receives a shell command, it executes the command\nvia [nohup](https://en.wikipedia.org/wiki/Nohup) on\nthe device shell to prevent hanging. Stdout, stderr, and return code are then\nretrieved from `nohup` and sent back to VTS agent. Finally, the agent\nreplies to the host by wrapping the command result(s) into a\n`protobuf` message.\n\n### Advantages\n\nThe advantages of using the VTS shell driver instead of `adb\nshell` include:\n\n- **Reliability.** The VTS shell driver uses `nohup` to execute commands on default setting. As VTS tests are mostly lower level HAL and kernel tests, `nohup` ensures shell commands do not hang during execution.\n- **Performance** . While the `adb shell` command caches some results (such as listing files in a directory) it has a connection overhead when performing tasks such as executing a test binary. VTS shell driver maintains an active connection throughout the test so the only overhead is USB communication. In our testing, using VTS shell driver to execute a command with 100 calls to an empty gtest binary is about 20 percent faster than using `adb shell`; the actual difference is larger since VTS shell communication has extensive logging.\n- **State-keeping** . The VTS shell driver maintains a terminal session for each terminal name (default terminal name is *default*). Environment variables set in one terminal session are available only to subsequent commands in the same session.\n- **Extendable**. Shell command communications between VTS framework and device driver are wrapped in protobuf to enable potential compression, remoting, encryption, etc. in the future. Other possibilities for improving performance are also available, including device-side result parsing when the communication overhead becomes larger than result string parsing.\n\n### Disadvantages\n\nThe disadvantages of using the VTS shell driver instead of `adb\nshell` include:\n\n- **Additional binaries**. VTS agent files must be pushed to device and cleaned up after test execution.\n- **Requires active connection** . If the TCP connection between host and agent is lost during testing (due to USB disconnection, port shutdown, device crash, etc.) either intentionally or unintentionally, a shell command cannot be transmitted to the VTS agent. Even with automatic switching to `adb shell`, the result and state of the command before disconnection would be unknown.\n\n### Examples\n\nExamples of using shell commands in a VTS host-side Python test script:\n\n- Get an Android device object: \n\n ```\n self.device = self.android_devices[0]\n ```\n- Get an shell object for the selected device: \n\n ```\n self.shell = self.device.shell\n ```\n- Issue a single shell command: \n\n ```\n results = self.shell.Execute(‘ls')\n ```\n- Issue a list of shell commands: \n\n ```\n results = self.shell.Execute([‘cd /data/local/tmp', ‘ls'])\n ```\n\n### Command result object\n\nThe return object from shell command execution is a dictionary containing the\nkeys `stdouts`, `stderrs`, and `return_codes`.\nRegardless of whether the shell command is provided as a single string or a list\nof command strings, each value of the result dictionary is always a list.\n\nTo verify the return code of a list of commands, the test script must check\nthe indices. Example: \n\n```\nasserts.assertFalse(any(results[‘return_codes']), ‘some command failed.')\n```\n\nAlternatively, the script can check each command index individually.\nExample: \n\n```\nasserts.assertEqual(results[‘return_codes'][0], 0, ‘first command failed')\n\nasserts.assertEqual(results[‘return_codes'][1], 0, ‘second command failed')\n```"]]
