سطر الأوامر ومشغّلات الاختبار

لماذا يهم

في الدرس السابق قرأت ملف اختبار؛ ولا يحدث شيء حتى يشغّله شيء ما. والمختبِر الذي لا يستطيع تشغيل حزمة الاختبارات من الطرفية (Terminal) يعتمد على غيره ليعرف هل المنتج معطّل، ولا يستطيع أن يعيد على جهازه إنتاج ما جعل خط الأنابيب (Pipeline) أحمر، ولا تضييق تشغيل يستغرق ساعتين إلى الاختبار الواحد المهم.

والطرفية أيضاً هي المكان الذي تظهر فيه الحقيقة دون تجميل: فالشارة الخضراء في لوحة المتابعة لا تعني إلا أن أمراً ما أعاد رمز الخروج 0. وعندما ترى السلسلة كاملة، الأمر فالمشغّل فالاختبارات فالتقرير فرمز الخروج، تستطيع أن تميّز عيباً في المنتج من تثبيت معطوب أو مجلد خاطئ أو مرشّح لم يطابق شيئاً، وأن تعطي المطورين الأمر الدقيق الذي يعيد إنتاج الإخفاق.

الطرفية: أين أنت وماذا تشغّل

كل أمر يعمل داخل مجلد العمل (Working Directory)، أي المجلد الذي تقف فيه الطرفية حالياً. يطبعه الأمر pwd، ويعرض ls محتوياته (dir في موجّه أوامر Windows القديم)، وينقلك cd tests إلى مجلد فرعي بينما يصعد بك cd .. مستوى واحداً. والمسار (Path) إما نسبي إلى ذلك المجلد (tests/login.spec.ts) وإما مطلق من جذر القرص (/home/sara/shop-tests أو C:\Users\sara\shop-tests). وكثير من مفاجآت «الأمر غير موجود» و«لم يُعثر على اختبارات» سببها مجرد طرفية تقف في المجلد الخطأ.

الأمر اسم برنامج تليه معاملات (arguments) وخيارات (options): في npx playwright test tests/login.spec.ts --headed يكون npx هو البرنامج، والملف معاملاً، و--headed خياراً. وتعثر الصدفة (Shell)، أي البرنامج الذي يقرأ ما تكتبه، على البرامج عبر متغير البيئة PATH، وهو قائمة مجلدات تبحث فيها عن برنامج بذلك الاسم. ومتغيرات البيئة (Environment Variables) قيم مسماة يتلقاها كل برنامج من الصدفة التي شغّلته، والقيمة التي تضبطها تبقى لنافذة الطرفية تلك وحدها. وتضع مشاريع الاختبار فيها كل ما يتغير بين جهاز وآخر، مثل عنوان الموقع قيد الاختبار أو كلمة مرور، فتبقى شيفرة الاختبار كما هي.

• في bash وzsh وGit Bash: export BASE_URL=https://staging.shop.example، أو لأمر واحد فقط: BASE_URL=https://staging.shop.example npx playwright test.
• في PowerShell: $env:BASE_URL = 'https://staging.shop.example'؛ وفي موجّه الأوامر: set BASE_URL=https://staging.shop.example.
• في Node.js تصل القيمة عبر process.env.BASE_URL؛ وإذا غاب المتغير كانت undefined، فينبغي أن يتحقق منه المشروع في البداية ويتوقف برسالة واضحة، بدلاً من أن يفشل لاحقاً على عنوان معطوب مثل undefined/login.
• Ctrl+C يوقف أمراً قيد التشغيل؛ ومفتاح Tab يكمل أسماء الملفات.

$ pwd                        # where am I?  (PowerShell: pwd works too; cmd.exe: cd)
/home/sara/shop-tests
$ ls                         # what is here?  (cmd.exe: dir)
node_modules  package.json  package-lock.json  playwright.config.ts  tests
$ cd tests && ls
checkout.spec.ts  login.spec.ts
$ cd ..
$ export BASE_URL=https://staging.shop.example   # PowerShell: $env:BASE_URL = '...'
$ npx playwright test

Node.js وnpm وnpx وملفا الحزمة

تعمل مشغّلات JavaScript مثل Playwright Test وJest وVitest على Node.js. ثبّت إصدار الدعم طويل الأمد (LTS) الحالي من nodejs.org وتحقق بـnode --version وnpm --version. وnpm، مدير الحزم (Package Manager) المرفق مع Node، ينزّل المكتبات التي يعتمد عليها المشروع إلى مجلد node_modules. أما npx فيشغّل برنامج سطر أوامر توفره إحدى تلك الحزم، وهو playwright هنا، دون تثبيت عام؛ وإذا لم تكن الحزمة في المشروع نزّلها npx إلى ذاكرة مؤقتة (cache) أولاً، بعد أن يطلب تأكيدك إذا كانت الطرفية تفاعلية.

يصف المشروعَ ملفان. package.json يكتبه البشر: scripts أسماء قصيرة لأوامر طويلة، فيشغّل npm test ما يقوله السكربت test، وdevDependencies قائمة حزم بنطاقات إصدارات، حيث يعني ^1.47.0 أي إصدار ⁦1.x⁩ من ⁦1.47.0⁩ فصاعداً. وpackage-lock.json يكتبه npm: الإصدار الدقيق لكل حزمة وحزمة فرعية ثُبّتت فعلاً. ويعامل npm install ملف القفل (Lock File) نقطةَ بداية: فإذا تغيّر package.json أو لم يوجد ملف قفل أعاد حلّ النطاقات، وقد يختار إصدارات أحدث، ويعيد كتابة ملف القفل. أما npm ci فيثبّت ما يقوله ملف القفل بالضبط، ويحذف node_modules الموجود أولاً، ويتوقف بخطأ إذا اختلف الملفان. ولهذا ينبغي أن يشغّل CI، وكل من يجهّز المشروع من الصفر، npm ci. ولا ينزّل npm ci المتصفحات التي يقودها Playwright: بل ينزّلها npx playwright install بعد تثبيت Playwright أو ترقيته، وعلى جهاز CI جديد يعمل بنظام Linux يضيف npx playwright install --with-deps أيضاً مكتبات النظام التي تحتاجها.

{
  "name": "shop-tests",
  "scripts": {
    "test": "playwright test",
    "test:smoke": "playwright test --grep @smoke"
  },
  "devDependencies": {
    "@playwright/test": "^1.47.0"
  }
}

جرّبها: مدقّق JSON

مثال تطبيقي: حزمة اختبارات تسجيل الدخول وعدة طرق لتشغيلها

في المشروع shop-tests ملف tests/login.spec.ts فيه ثلاثة اختبارات، اثنان منها موسومان بـ@smoke، وملف tests/checkout.spec.ts فيه أربعة أخرى. هذه أوامر Playwright Test؛ وللمشغّلات الأخرى الأشكال نفسها بتهجئة مختلفة.

يأخذ -g (أي --grep) تعبيراً نمطياً (Regular Expression)، وهو نمط نصي أبسط حالاته كلمة عادية، ويطابقه مع العنوان الكامل بما فيه أسماء describe، فيشغّل -g Login المجموعة كلها؛ والوسم (Tag) كلمة مثل @smoke تُرشَّح بالطريقة نفسها. وفي PowerShell اكتب الوسم بين علامتي اقتباس، --grep '@smoke'، لأن PowerShell يقرأ @smoke دون اقتباس على أنها متغير فيضيع المرشّح. والوضع بلا واجهة (Headless)، وهو الافتراضي، يشغّل المتصفح دون نافذة. أما --headed فيُظهر النافذة، و--debug يفتح مفتّش Playwright (Inspector) والاختبار متوقف لتتقدم فيه إجراءً بإجراء، و--ui يتيح لك المشاهدة وإعادة التشغيل. والثلاثة لجهازك أنت؛ فليس في CI شاشة.

Goal                           Command
All tests                      npx playwright test
One file                       npx playwright test tests/login.spec.ts
By title (regular expression)  npx playwright test -g "wrong password"
By tag                         npx playwright test --grep @smoke
Headed: watch the browser      npx playwright test --headed
Debug: step through actions    npx playwright test tests/login.spec.ts --debug
One browser project only       npx playwright test --project=chromium
Through package.json scripts   npm test          npm run test:smoke

جرّبها: أداة اختبار Regex

كيف يعثر المشغّل على الاختبارات وماذا يطبع

لا يشغّل المشغّل «المشروع»، بل يكتشف ملفات. يبحث Playwright Test في testDir المضبوط عن ملفات تنتهي أسماؤها افتراضياً بلواحق مثل .spec.ts أو .spec.js أو .test.ts أو .test.js، ويحمّلها، ويجمع كل استدعاء test() مرتّباً ضمن كتل test.describe()؛ وتستخدم Jest وVitest البنية نفسها بـdescribe وit أو test، وMocha بـdescribe وit. والملف الذي لا يطابق النمط يُتجاهل بصمت، وهذا سبب شائع لاختبار جديد «لم يعمل».

اقرأ المخرجات من أعلى إلى أسفل: الترويسة تعدّ الاختبارات التي عُثر عليها والعمّال (workers)، أي العمليات المتوازية التي تشغّلها؛ وكل سطر اختبار واحد بحالته وملفه ورقم سطره وعنوانه؛ وتُكرَّر حالات الفشل في النهاية مع رسالة التأكيد (Assertion) وتتبّع المكدس (Stack Trace)؛ والسطور الأخيرة تعدّ ما فشل، وما تذبذب (flaky، أي فشل ثم نجح عند إعادة المحاولة)، وما تُخطّي، وما نجح. ويكتب مولّد التقارير (Reporter) html، إذا فعّله الإعداد، تقريره في playwright-report/ (افتحه بـnpx playwright show-report)، وتذهب لقطات الشاشة وآثار (traces) الاختبارات الفاشلة، إذا فعّلها الإعداد، إلى test-results/، ويكتب مولّد التقارير junit تقرير XML، في ملف يُسمّى في الإعداد عادةً، تحوّله خوادم CI إلى عرض لكل اختبار على حدة.

// tests/login.spec.ts — what the runner collects
import { test, expect } from '@playwright/test';

test.describe('Login', () => {
  test('valid login reaches dashboard', { tag: '@smoke' }, async ({ page }) => {
    // arrange, act, assert
  });
  test('wrong password shows error', { tag: '@smoke' }, async ({ page }) => {
    // ...
  });
  test('locked account is refused', async ({ page }) => { /* ... */ });
});

// npx playwright test tests/login.spec.ts — the list reporter
Running 3 tests using 1 worker

  ✓  1 [chromium] › login.spec.ts:4:7 › Login › valid login reaches dashboard (2.1s)
  ✘  2 [chromium] › login.spec.ts:7:7 › Login › wrong password shows error (1.4s)
  ✓  3 [chromium] › login.spec.ts:10:7 › Login › locked account is refused (1.2s)

  1) [chromium] › login.spec.ts:7:7 › Login › wrong password shows error

    Error: expect(locator).toHaveText(expected) failed
    Expected string: "Wrong e-mail or password"
    Received string: "Invalid credentials"

  1 failed
    [chromium] › login.spec.ts:7:7 › Login › wrong password shows error
  2 passed (5.0s)

جرّبها: مقارنة النصوص (Diff)

رموز الخروج: كيف يعرف CI النتيجة

ينتهي كل برنامج برمز خروج (Exit Code)، وهو رقم يعيده نظام التشغيل إلى من شغّل البرنامج. وبالاصطلاح يعني 0 النجاح وأي شيء آخر الفشل. ولا يخرج مشغّل الاختبارات بـ0 إلا إذا لم يفشل أي اختبار؛ فاختبار فاشل، أو خطأ في ملف الإعدادات، أو مرشّح لم يطابق شيئاً، أو متصفح غير مثبّت، كلها تعطي رمزاً غير صفري. وبعد الأمر مباشرةً يطبعه echo $? في bash، و$LASTEXITCODE في PowerShell، و%ERRORLEVEL% في موجّه الأوامر.

خوادم CI مثل GitHub Actions وGitLab CI وJenkins لا تقرأ الألوان: بل تشغّل كل خطوة بوصفها أمراً، وتعدّ الخطوة فاشلة عندما يكون رمز خروجها غير صفري، فتتوقف المهمة وتحمرّ، ويُحجب الدمج حيث جعل الفريق هذا الفحص إلزامياً. هذا هو العقد كله. ويعني أيضاً أن مشغّلاً يبتلع حالات الفشل ويخرج بـ0 يعطي مهمة خضراء لمنتج معطّل، وأن اختباراً متذبذباً يفشل بين حين وآخر يجعل المهمة حمراء حتى لو كان المنتج يعمل. وتُكتب الخطوات نفسها في ملف خط أنابيب داخل المستودع: ملف سير عمل بصيغة YAML في .github/workflows/ لـGitHub Actions، أو .gitlab-ci.yml لـGitLab CI (ويستخدم Jenkins ملف Jenkinsfile)، وكل مدخل run: أو script: فيه أمرٌ كالأوامر التي في هذا الدرس.

• Python: يثبّت pip install -r requirements.txt الاعتماديات؛ ويشغّل pytest tests/test_login.py -k wrong_password ملفاً واحداً مرشَّحاً بكلمة مفتاحية من اسم الاختبار، ويختار -m smoke علامة (marker)؛ ويخرج pytest بـ0 إذا عملت الاختبارات المختارة ولم يفشل أي منها، وبـ1 إذا فشل اختبار، وبـ5 إذا لم يُجمع أي اختبار.
• Java: يقرأ Maven ملف pom.xml؛ ويشغّل mvn test حزمة الاختبارات ويشغّل mvn -Dtest=LoginTest test صنفاً واحداً؛ والاختبار الفاشل يُفشل البناء برمز خروج غير صفري.

$ npx playwright test --grep @smoke
  1 failed
  2 passed (6.8s)
$ echo $?                    # PowerShell: $LASTEXITCODE    cmd.exe: echo %ERRORLEVEL%
1

جرّبها: منسّق YAML

أسئلة شائعة

المراجع

• Playwright DocumentationMicrosoft (Playwright)التوثيق الرسمي لـ Playwright، إطار الاختبار الشامل الذي يشغّل Chromium وWebKit وFirefox.
• Continuous Integration (Martin Fowler)martinfowler.com · 2024الوصف الأكثر استشهاداً للتكامل المستمر: ادمج كثيراً، واجعل البناء يختبر نفسه وسريعاً، وأصلح البناء المكسور فوراً.
• GitHub Actions documentationGitHubكيف تُعرَّف مسارات العمل والمهام والمشغّلات والمخرجات في GitHub Actions — حيث تعمل الاختبارات الآلية عند كل دفع أو طلب دمج.
• Certified Tester Advanced Level Test Automation Engineering (CTAL-TAE) v2.0ISTQB · 2024منهج ISTQB المتقدم لتصميم حلول أتمتة الاختبار وتنفيذها وصيانتها وبنيتها.