الانتقال من Applitoolsوصول مبكر

انقل مجموعة اختبارات Playwright من Applitools Eyes إلى Delta-QA

تعمل مجموعة اختبارات Playwright المكتوبة لـ Applitools Eyes على Delta-QA بعد تغييرين: الاستيراد ومتغيرات البيئة. وتبقى eyes.open وcheck وclose وBatchInfo وaddBrowser والمناطق كما هي.

التثبيت، وتغيير الاستيراد

تعتمد واجهة Eyes البرمجية في @delta-qa/vision أسماء Applitools Eyes الخاصة بـ Playwright ومعانيها. وتتطلب Node.js 22 أو أحدث و@playwright/test 1.62 أو أحدث.

تتوفر حزمة Vision SDK أولًا بالوصول المبكر: تواصل معنا لاستخدامها في مجموعة اختباراتك. اطلب الوصول إلى Vision

Applitools	Delta-QA
`import { test } from "@applitools/eyes-playwright/fixture";`	`import { test } from "@delta-qa/vision/eyes/fixture";`
`import type { EyesFixture } from "@applitools/eyes-playwright/fixture";`	`import type { EyesFixture } from "@delta-qa/vision/eyes/fixture";`
`import { Eyes, Target, … } from "@applitools/eyes-playwright";`	`import { Eyes, Target, … } from "@delta-qa/vision/eyes";`

يبقى eyesConfig في playwright.config كما هو. ومع الـ fixture، لا يغيّر الاختبار سوى الاستيراد:

// import { test } from "@applitools/eyes-playwright/fixture";
import { test } from "@delta-qa/vision/eyes/fixture";

test("checkout", async ({ page, eyes }) => {
  await page.goto("https://shop.example/cart");
  await eyes.check("Cart", { fully: true });
}); // opened before the test, closed by the fixture

اضبط متغيرات البيئة

المتغير	يُقرأ من أجل
`DELTAQA_API_KEY`	مفتاح API لمساحة عمل Delta-QA الخاصة بك (`dqa_…`)، بالدور «Can edit»، يُنشأ من Settings → Workspace → API keys. احفظه في سرّ ضمن CI.
`APPLITOOLS_API_KEY`	يُقرأ عندما لا يكون `DELTAQA_API_KEY` مضبوطًا: احتفظ بالمتغير، وأعطه مفتاح Delta-QA.
`DELTAQA_SERVER_URL`	خادم Delta-QA الخاص بك، لتثبيت On-Premise؛ وسحابة Delta-QA عند عدم ضبطه. لا يُقرأ `APPLITOOLS_SERVER_URL` أبدًا.
`APPLITOOLS_BATCH_ID`	الإصدار المختبَر — أي الـ commit. ويتقدّم عليه `id` الدفعة المحدد في الشيفرة البرمجية.
`APPLITOOLS_BRANCH`	الفرع. ويتقدّم عليه `setBranchName` في الشيفرة البرمجية.
`APPLITOOLS_PARENT_BRANCH` `APPLITOOLS_BASELINE_BRANCH`	الفرع الأساسي، الذي يُستخدم مرجعه ما دام الفرع بلا مرجع. يتقدّم `APPLITOOLS_BASELINE_BRANCH` على `APPLITOOLS_PARENT_BRANCH`؛ والشيفرة البرمجية تتقدّم على كليهما.

تُقرأ أيضًا صيغ _NAME لمتغيرات الفرع (APPLITOOLS_BRANCH_NAME وAPPLITOOLS_PARENT_BRANCH_NAME وAPPLITOOLS_BASELINE_BRANCH_NAME). ويُعامَل المتغير الفارغ كمتغير غير مضبوط. وبدون مفتاح، يفشل فتح الاختبار ويسمّي المتغير الواجب ضبطه.

متغيرات Applitools هذه لا تُقرأ، ولا تُصدر تحذيرًا: APPLITOOLS_SERVER_URL, APPLITOOLS_BATCH_NAME, APPLITOOLS_DONT_CLOSE_BATCHES, APPLITOOLS_SHOW_LOGS.

اضبط CI لديك

لا تقرأ الحزمة git ولا متغيرات CI لديك: الأسطر أدناه تستخرج منها الفرع والفرع الأساسي والـ commit، وتضعها في متغيرات Applitools الثلاثة.

GitHub Actions

عند push، يكون github.head_ref فارغًا: فيكون الفرع حينئذٍ github.ref_name. وفي pull request، يكون github.sha هو commit الدمج الذي ينشئه GitHub، لا الـ commit المدفوع: لذا يتقدّم عليه commit الرأس.

env:
  APPLITOOLS_BRANCH: ${{ github.head_ref || github.ref_name }}
  APPLITOOLS_PARENT_BRANCH: ${{ github.base_ref || github.event.repository.default_branch }}
  APPLITOOLS_BATCH_ID: ${{ github.event.pull_request.head.sha || github.sha }}

GitLab CI

في pipeline لطلب دمج (merge request)، يكون CI_MERGE_REQUEST_TARGET_BRANCH_NAME هو الفرع الهدف؛ وفي pipeline لفرع، يكون فارغًا.

script:
  - export APPLITOOLS_BRANCH="${CI_MERGE_REQUEST_SOURCE_BRANCH_NAME:-$CI_COMMIT_REF_NAME}"
  - export APPLITOOLS_PARENT_BRANCH="${CI_MERGE_REQUEST_TARGET_BRANCH_NAME:-$CI_DEFAULT_BRANCH}"
  - export APPLITOOLS_BATCH_ID="$CI_COMMIT_SHA"
  - npx playwright test

Bitbucket Pipelines

لا يُضبط BITBUCKET_PR_DESTINATION_BRANCH إلا في pipeline لطلب سحب (pull request).

script:
  - export APPLITOOLS_BRANCH="$BITBUCKET_BRANCH"
  - export APPLITOOLS_PARENT_BRANCH="$BITBUCKET_PR_DESTINATION_BRANCH"
  - export APPLITOOLS_BATCH_ID="$BITBUCKET_COMMIT"
  - npx playwright test

Azure Pipelines

لا تُضبط متغيرات System.PullRequest إلا في build لطلب سحب (pull request)، بالشكل refs/heads/… في Azure Repos. ولا يحتفظ Build.SourceBranchName إلا بالمقطع الأخير من اسم الفرع (feature/cart يعطي cart)، لذا يُقرأ الفرع من الـ ref الكامل.

- script: |
    branch="${SYSTEM_PULLREQUEST_SOURCEBRANCH:-$BUILD_SOURCEBRANCH}"
    base="${SYSTEM_PULLREQUEST_TARGETBRANCH:-}"
    export APPLITOOLS_BRANCH="${branch#refs/heads/}"
    export APPLITOOLS_PARENT_BRANCH="${base#refs/heads/}"
    export APPLITOOLS_BATCH_ID="${SYSTEM_PULLREQUEST_SOURCECOMMITID:-$BUILD_SOURCEVERSION}"
    npx playwright test

لا يُستخدم فرع أساسي مطابق للفرع نفسه: على الفرع الافتراضي، لا تعطي هذه الأسطر أي فرع أساسي.

أغلق في مرحلة التفكيك (teardown)، لا في متن الاختبار أبدًا

مع الـ fixture، يُغلق eyes في مرحلة تفكيك الاختبار. وبدونها، استدعِ eyes.close() في afterEach، وrunner.getAllTestResults() في afterAll.

لا تُغلق أبدًا في متن الاختبار: انتظار الحكم يستهلك وقت الاختبار — 30 ثانية افتراضيًا في Playwright Test — والخطوة التي تفشل قبل close() تترك الاختبار مفتوحًا. أما مرحلة التفكيك فلها مهلتها الخاصة.

import { test } from "@playwright/test";
import { Eyes, Target, VisualGridRunner } from "@delta-qa/vision/eyes";

const runner = new VisualGridRunner();
let eyes: Eyes;

test.beforeEach(async ({ page }) => {
  eyes = new Eyes(runner);
  await eyes.open(page, "Shop", test.info().title);
});
test("checkout", async ({ page }) => {
  await page.goto("https://shop.example/cart");
  await eyes.check("Cart", Target.window().fully());
});
test.afterEach(async () => {
  await eyes.close(); // throws DiffsFoundError when a difference awaits a judgment
});
test.afterAll(async () => {
  await runner.getAllTestResults();
});

كل إعداد من إعدادات Applitools، وما يصبح عليه

كل إعدادات Applitools Eyes مقبولة: تُصرَّف مجموعة الاختبارات وتعمل. وكل إعداد إما يطبقه Delta-QA، وإما يُقبل بلا أثر مع تحذير. وبعض الاستدعاءات غير موجودة.

مطبَّقة

الإعداد	في Delta-QA
`appName`	تطبيق الاختبار؛ ومع اسم الاختبار، يحدد هويته. في `eyesConfig`، تكون القيمة `My App` عند عدم ضبطه، كما في fixture الخاصة بـ Applitools.
`testName`	اسم الاختبار، أي مفتاحه: الاسم المتغيّر يعني اختبارًا جديدًا. في `eyesConfig`، يمكن أيضًا أن يكون دالة للاختبار؛ وبدونه، يُستخدم مسار عناوين الاختبار بلا ملفه (`describe > test`)، كما في fixture الخاصة بـ Applitools.
`apiKey` `setApiKey`	المفتاح، بدلًا من `DELTAQA_API_KEY` أو `APPLITOOLS_API_KEY` — مفتاح Delta-QA. لا يظهر أبدًا في رسالة ولا في سجل ولا في رابط.
`branchName`	فرع التشغيل؛ وبدونه، `APPLITOOLS_BRANCH` ثم `APPLITOOLS_BRANCH_NAME`.
`parentBranchName` `baselineBranchName`	الفرع الأساسي، `baselineBranchName` قبل `parentBranchName`؛ وبدونهما، متغيراهما بالترتيب نفسه.
`batch`	الـ `id` الخاص بالدفعة هو الإصدار المختبَر — أي الـ commit؛ وبدونه، `APPLITOOLS_BATCH_ID`؛ وبدونهما معًا، إصدار واحد لكل عملية (انظر الفروق أدناه).
`saveNewTests`	هل تصبح صفحات الاختبار الجديد مرجعه؛ `true` عند عدم ضبطه.
`viewportSize`	الحجم المعطى للصفحة عند فتح الاختبار.
`browsersInfo` `addBrowser(width, height)`	كل حجم بيئة، لـ Chrome أو بلا اسم متصفح. وتُقرأ لغتها ومنطقتها الزمنية وسِمتها وكثافة شاشتها من متصفح الاختبار.
`fully` `fully(true)`	الصفحة كاملة — وهو ما يتحقق منه Delta-QA في كل الأحوال.
`withName` `name`	اسم الـ check.
`Target.window`	صفحة الاختبار.
`Target.region` `CheckSettings.region` `checkRegion` `checkRegionBy` `checkRegionByElement` `checkElement` `checkElementBy`	الجزء الوحيد من الصفحة الذي يُقارَن: أول عنصر يشير إليه locator أو محدِّد (selector) أو مقبض عنصر (element handle)، كما في Applitools؛ وآخر منطقة تُعطى هي التي تُعتمد. وتُستبعد مناطق التجاهل التي تحتويها.
`ignoreRegions` `ignoreRegion` `ignore` `ignores`	كل عنصر تشير إليه منطقة — locator، أو محدِّد، أو `{ selector, type }`، أو مقبض عنصر — يُستبعد من المقارنة: كل عناصر الـ locator، كما في Applitools. وكذلك الصيغة `{ region }` والمفتاح `ignoreRegions` في صيغة الكائن.
`eyesConfig.failTestsOnDiff`	متى يُفشل الحكمُ الذي ليس `PASSED`، داخل الـ fixture: مع `'afterEach'` يفشل الاختبار عند تفكيكه؛ ومع `'afterAll'` يفشل الـ worker بعد انتهاء اختباراته؛ ومع `false` لا يفشل شيء، مع انتظار الحكم رغم ذلك. وبدونه، `'afterAll'` عندما يكون المتغير `CI` مضبوطًا و`'afterEach'` في غير ذلك، كما تقرر الشيفرة البرمجية لـ fixture الخاصة بـ Applitools.
`eyesConfig.afterAll`	يُستدعى بعد انتهاء اختبارات الـ worker، مع نتيجة كل منها.

الاستدعاءات

الاستدعاء	في Delta-QA
`open(page, appName, testName, viewportSize?)`	يُعرَّف الاختبار بتطبيقه واسمه: الاسم المتغيّر يعني اختبارًا جديدًا. ويُعطى حجم نافذة العرض للصفحة.
`check(name?, Target.window())` `checkWindow(tag?)`	يفحص الصفحة كما هي، في كل بيئة. الـ check بلا اسم يُربط بمرجعه عبر عنوان صفحته؛ ويُقبل وجود اثنين من الـ check بالاسم نفسه. ويعيد `MatchResult` بلا حكم، كما يفعل `check` في Applitools: يأتي الحكم عند الإغلاق.
`close(throwErr = true)`	ينتظر الحكم: `DiffsFoundError` عند فرق ينتظر الحكم، و`NewTestError` عند اختبار جديد ينتظر الحكم (`saveNewTests(false)`)، و`TestFailedError` عند فرق حُكم عليه بـ «Bug» أو عند فشل. وتعطي الرسالة رابط الإصدار في Delta-QA.
`closeAsync()` `runner.getAllTestResults(throwErr = true)`	`closeAsync()` يُغلق دون انتظار؛ وينتظر الـ runner كل حكم، ويُغلق الاختبار الذي بقي مفتوحًا، ويرمي خطأً عند اختبار لم ينجح — ويحتفظ له بخطأ `closeAsync()`.
`abort()` `abortIfNotClosed()` `abortAsync()`	يُغلق دون انتظار الحكم، ولا يُفشل شيئًا: تُوسَم النتائج بأنها مُلغاة، بلا نتيجة؛ و`null` عندما لا يكون أي اختبار مفتوحًا. ومع ذلك يقارن Delta-QA عمليات التشغيل، ويعرض الإصدار نتيجتها.

غير موجودة: ما لا يُصرَّف

هذه ليست إعدادات: إنها تعيد بيانات لا يملكها Delta-QA، أو تتحقق من صورة بدلًا من صفحة. ومجموعة الاختبارات التي تستخدمها لا تُصرَّف، بدلًا من أن تتلقى قيمة مختلَقة.

غير موجود	السبب
`eyes.locate` `eyes.extractText` `eyes.extractTextRegions`	تعيد مناطق أو نصًا يقرؤه Applitools في لقطته.
`eyes.checkImage` `Target.image` `Target.buffer` `Target.base64` `Target.path` `Target.url`	يتحقق Delta-QA من الصفحات، لا من الصور.
`eyes.getLogger` `eyes.logger`	سجل Applitools.
`eyes.run`	في fixture الخاصة بـ Applitools، الـ check باللغة الطبيعية.

ما يختلف عن Applitools

خيارات مقصودة في Delta-QA، ينبغي معرفتها قبل التشغيل الأول.

الحالة	Delta-QA
ربط الـ check بمرجعه	باسم الـ check عندما يكون كل اسم فريدًا داخل الاختبار؛ وإلا فبالترتيب، بالاسم، وإلا بعنوان الصفحة: إضافة check أو حذفه لا يزيح الباقي.
تغيير مقبول على فرع	لا دمج تلقائي للمراجع من فرع إلى آخر. وعندما يظهر الفرق نفسه على فرع آخر، يقترح Delta-QA «Already intended on … — apply?».
قبول فرق	«سلوك متوقع» يُطبَّق على الفروع التي تحددها.
لا `APPLITOOLS_BATCH_ID` ولا `id` للدفعة	إصدار واحد لكل عملية: كل worker في Playwright Test عملية مستقلة، لذا تنتج عدة workers عدة إصدارات — مع الـ fixture أيضًا. اضبط `APPLITOOLS_BATCH_ID` على commit الـ CI لديك لتتشارك إصدارًا واحدًا.
منطقة تجاهل لا تطابق أي عنصر	تُستبعد، ويُرسل الـ check بدونها، كما يفعل Applitools — ويسمّيها تحذير Node.js برمز `DELTAQA_IGNORED_REGION`، مرة واحدة لكل منطقة ولكل عملية (ويُسكته `node --disable-warning=DELTAQA_IGNORED_REGION`). أما منطقة التحقق التي لا تطابق شيئًا فتُفشل الـ check بـ `ZoneNotFoundError`، كما في Applitools.
`runner.getAllTestResults()` واختبار بقي مفتوحًا	يُغلق الاختبار ويُعطى حكمه؛ أما Applitools فيلغيه.
الـ fixture: `eyesConfig` في أعلى `playwright.config` وفي مشروع	إعداد المشروع يحل محل الإعداد العلوي، كما يعطي Playwright Test خيارًا؛ ويضيف `test.use` مفاتيحه إلى إعداد المشروع. أما fixture الخاصة بـ Applitools فتدمج الاثنين مفتاحًا بمفتاح.
الـ fixture: `type: 'classic'` مع `browsersInfo`	كل حجم بيئة، كما مع `ClassicRunner` خارج الـ fixture؛ أما fixture الخاصة بـ Applitools فتُسقط الأحجام. ويُصدر `type` تحذيرًا.
الـ fixture: `expect(page).toHaveScreenshot()`	الخاص بـ Playwright Test: `expect` هو الخاص بـ `@playwright/test`. أما fixture الخاصة بـ Applitools فتحوّله إلى check من Eyes.
اختبار بقي بلا check مدة 30 دقيقة	يُغلقه Delta-QA؛ ثم يقرأ `close()` حكمه.

البيانات التي ترسلها

ما ترسله الحزمة — الصفحات التي تتحقق منها اختباراتك والملفات التي تستخدمها — لا يُستخدم إلا لمقارنتها. والاختبار على بيانات إنتاج شخصية مسؤوليتك: شغّل مجموعة الاختبارات على بيانات اختبار.

Vision SDK: عمليات تحقق Delta-QA في اختبارات Playwright لديك

Applitools وApplitools Eyes وEyes علامات تجارية لشركة Applitools Ltd. وDelta-QA غير تابع لـ Applitools، ولا معتمد منها، ولا برعايتها.

شغّل مجموعة اختبارات Eyes على Delta-QA

لاستخدام Vision، تواصل معنا: تتوفر أولًا بالوصول المبكر. أخبرنا بالاختبارات التي تريد التحقق منها، ونفتح لك الوصول.

اطلب الوصول إلى Vision أنشئ حسابًا مجانيًا

انقل مجموعة اختبارات Playwright من Applitools Eyes إلى Delta-QA

التثبيت، وتغيير الاستيراد

اضبط متغيرات البيئة

اضبط CI لديك

GitHub Actions

GitLab CI

Bitbucket Pipelines

Azure Pipelines

أغلق في مرحلة التفكيك (teardown)، لا في متن الاختبار أبدًا

كل إعداد من إعدادات Applitools، وما يصبح عليه

مطبَّقة

الاستدعاءات

مقبولة بلا أثر

إعدادات المقارنة

إعدادات لقطة الشاشة

المتصفحات والأجهزة والبيئات

شبكة العرض في Applitools

الدفعات والمراجع والنتائج

Git

الخادم والاتصال والسجلات

ميزات خارج Delta-QA

مناطق بلا عنصر

غير موجودة: ما لا يُصرَّف

ما يختلف عن Applitools

البيانات التي ترسلها

شغّل مجموعة اختبارات Eyes على Delta-QA