بدء استخدام اختبارات حلقة الألعاب لأجهزة iOS

باستخدام اختبارات Game Loop، يمكنك كتابة اختبارات أصلية لمحرك اللعبة ثم تنفيذها في Test Lab على الأجهزة التي تختارها. بهذه الطريقة، لن يكون عليك القلق بشأن الكتابة لإطارات عمل مختلفة لاختبارات أو واجهات مستخدم. يحاكي اختبار "حلقة الألعاب" إجراءات لاعب حقيقي، وعند تشغيله على Test Lab، فإنه يوفر طريقة سريعة وقابلة للتطوير للتحقّق من أنّ لعبتك تعمل بشكل جيد للمستخدمين.

توضّح لك هذه الصفحة كيفية إجراء اختبار "حلقة الألعاب"، ثم عرض نتائج الاختبار وإدارتها في صفحة Test Lab ضمن وحدة تحكّم Firebase. يمكنك أيضًا تخصيص اختباراتك بشكل أكبر باستخدام ميزات اختيارية، مثل كتابة نتائج اختبار مخصّصة أو إنهاء الاختبار مبكرًا.

ملاحظة: يمكنك استخدام Test Lab بدون أي رسوم من خلال خطة Spark السعرية التي تتضمّن حصة يومية محدودة. لمزيد من المعلومات عن خطط الأسعار الأخرى وحدود الاستخدام، اطّلِع على خطط أسعار Firebase.

ما هو اختبار حلقة الألعاب؟

حلقة الألعاب هي عبارة عن جولة كاملة أو جزئية من الاختبار على تطبيق الألعاب. يمكنك إجراء اختبار حلقة الألعاب محليًا على جهاز محاكاة أو على مجموعة من الأجهزة في Test Lab. يمكن استخدام اختبارات "حلقة الألعاب" لإجراء ما يلي:

• شغِّل لعبتك كما يفعل المستخدم النهائي. يمكنك إما كتابة نص لإدخال المستخدم أو السماح للمستخدم بترك الجهاز بدون تفاعل أو استبدال المستخدم بذكاء اصطناعي (على سبيل المثال، إذا كنت قد نفّذت الذكاء الاصطناعي في لعبة سباق سيارات، يمكنك تعيين سائق ذكاء اصطناعي مسؤولاً عن إدخال المستخدم).

• شغِّل لعبتك بأعلى إعدادات الجودة لمعرفة الأجهزة التي يمكنها تشغيلها.

• يمكنك إجراء اختبار فني، مثل تجميع عدّة أدوات تصفية ضوئية وتنفيذها والتحقّق من أنّ النتيجة على النحو المتوقّع.

الخطوة 1: تسجيل مخطّط عناوين URL المخصّص Test Lab

أولاً، عليك تسجيل مخطّط عناوين URL المخصّص في "Firebase Test Lab" في تطبيقك:

1. في Xcode، اختَر هدف مشروع.

2. انقر على علامة التبويب معلومات، ثم أضِف نوع عنوان URL جديدًا.

3. في الحقل مخطّطات عناوين URL، أدخِل firebase-game-loop. يمكنك أيضًا تسجيل مخطّط عنوان URL المخصّص من خلال إضافته إلىملف إعدادات Info.plist الخاص بمشروعك في أيّ مكان ضمن علامة <dict>:

   <key>CFBundleURLTypes</key>
    <array>
        <dict>
            <key>CFBundleURLName</key>
            <string></string>
            <key>CFBundleTypeRole</key>
            <string>Editor</string>
            <key>CFBundleURLSchemes</key>
            <array>
                <string>firebase-game-loop</string>
            </array>
        </dict>
    </array>
   

تم إعداد تطبيقك الآن لإجراء اختبار باستخدام Test Lab.

الخطوة 2 (اختيارية): ضبط تطبيقك لتشغيل عدة حلقات

إذا كان تطبيقك يتضمّن مخطّطات عناوين URL مخصّصة متعددة مسجّلة وكنت تخطّط لتنفيذ حلقات متعدّدة (المعروفة أيضًا باسم السيناريوهات) في اختبارك، عليك تحديد الحلقات التي تريد تنفيذها في تطبيقك في وقت الإطلاق.

في رمز التفويض الخاص بالتطبيق، يمكنك إلغاء طريقة application(_:open:options:):

Swift

func application(_app: UIApplication,
                 open url: URL
                 options: [UIApplication.OpenURLOptionsKey : Any] = [:]) -> Bool {
    let components = URLComponents(url: url, resolvingAgainstBaseURL: true)!
    if components.scheme == "firebase-game-loop" {
        // ...Enter Game Loop Test logic to override application(_:open:options:).
    }
    return true
}

Objective-C

- (BOOL)application:(UIApplication *)app
            openURL:(NSURL *)url
            options:(NSDictionary <UIApplicationOpenURLOptionsKey, id> *)options {
  if ([url.scheme isEqualToString:(@"firebase-game-loop")]) {
      // ...Enter Game Loop Test logic to override application(_:open:options:).
  }
}

عند تشغيل عدة حلقات في اختبارك، يتم تمرير الحلقة الحالية كمَعلمة إلى عنوان URL المستخدَم لتشغيل التطبيق. يمكنك أيضًا الحصول على رقم المحاولة الحالية من خلال تحليل العنصر URLComponents المستخدَم لجلب مخطّط عنوان URL المخصّص:

Swift

if components.scheme == "firebase-game-loop" {
    // Iterate over all parameters and find the one with the key "scenario".
    let scenarioNum = Int(components.queryItems!.first(where: { $0.name == "scenario" })!.value!)!
    // ...Write logic specific to the current loop (scenarioNum).
}

Objective-C

if ([url.scheme isEqualToString:(@"firebase-game-loop")]) {
    // Launch the app as part of a game loop.
    NSURLComponents *components = [NSURLComponents componentsWithURL:url
                                             resolvingAgainstBaseURL:YES];
    for (NSURLQueryItem *item in [components queryItems]) {
        if ([item.name isEqualToString:@"scenario"]) {
            NSInteger scenarioNum = [item.value integerValue];
            // ...Write logic specific to the current loop (scenarioNum).
        }
    }
}

الخطوة 3: إنشاء اختبار وتنفيذه

بعد تسجيل مخطّط عناوين URL المخصّص في Test Lab، يمكنك إجراء الاختبار في وحدة تحكّم Firebase أو باستخدام واجهة سطر أوامر gcloud التجريبية. أنشئ ملف IPA لتطبيقك إذا لم يسبق لك ذلك (ستحتاج إلى تحديد موقعه لاحقًا).

ملاحظة: قبل استخدام Test Lab، يمكنك أولاً التأكّد من أنّ حلقات اللعبة تعمل على النحو المطلوب من خلال إجراء الاختبار على جهاز محاكاة.

إنشاء حزمة IPA لتطبيقك

1. في Xcode، اختَر ملفًا شخصيًا لتوفير الخدمة للتطبيق المستهدَف.
   ملاحظة: يُعيد Test Lab توقيع تطبيقك باستخدام ملف التوفير الخاص به وشهادته.
2. من القائمة المنسدلة التي تظهر، انقر على المنتج > الأرشيف. اختَر أحدث إصدار في الأرشيف، ثم انقر على نشر التطبيق.
3. في النافذة التي تظهر، انقر على التطوير > التالي.
4. اختياري: للحصول على إصدار أسرع، أزِل العلامة من المربّع بجانب الخيار إعادة الإنشاء من رمز Bitcode، ثم انقر على التالي. لا يتطلّب Test Lab تقليل حجم تطبيقك أو إعادة إنشائه لإجراء اختبار، ما يتيح لك إيقاف هذا الخيار بأمان.
5. انقر على تصدير، ثم أدخِل دليلاً تريد تنزيل ملف IPA الخاص بتطبيقك فيه.

إجراء اختبار في وحدة تحكّم Firebase

1. افتح وحدة تحكّم Firebase وأنشئ مشروعًا، إذا لم يسبق لك ذلك.

2. في صفحة Test Lab من وحدة تحكّم Firebase، انقر على إجراء أول اختبار > تشغيل حلقة ألعاب iOS.

3. في قسم تحميل التطبيق، انقر على تصفّح، ثم اختَرملف IPA لتطبيقك (أنشئ ملف IPA لتطبيقك إذا لم يسبق لك ذلك).

4. اختياري: إذا كنت تريد تنفيذ عدة حلقات (المعروفة أيضًا باسم السيناريوهات) في المرة الواحدة أو اختيار حلقات معيّنة لتشغيلها، أدخِل أرقام الحلقات في حقل السيناريوهات.

   على سبيل المثال، عند إدخال "1-3، 5"، يُجري Test Lab الحلقات 1 و2 و3 و5. بشكلٍ تلقائي (إذا لم تُدخل أيّ شيء في حقل السيناريوهات)، لن يؤدي Test Lab إلى تنفيذ سوى حلقة 1.

5. في قسم الأجهزة، اختَر جهازًا واحدًا أو أكثر تريد اختبار تطبيقك عليه، ثم انقر على بدء الاختبارات.

إجراء اختبار باستخدام gcloud beta CLI

ملاحظة: إنّ الأمر gcloud beta CLI لاختبارات حلقة الألعاب على نظام التشغيل iOS هو إصدار تجريبي. ويعني ذلك أنّ الوظيفة قد تتغيّر بطرق غير متوافقة مع الأنظمة القديمة. لا يخضع الإصدار التجريبي لأي اتفاقية مستوى خدمة أو سياسة إيقاف نهائي، وقد يحصل على دعم محدود أو لا يحصل على أي دعم.

1. عليك ضبط بيئة gcloud SDK المحلية، إذا لم يسبق لك ذلك، ثم التأكّد من تثبيت مكوّن gcloud التجريبي.

2. شغِّل الأمر gcloud beta firebase test ios run واستخدِم العلامات التالية لضبط عملية التشغيل:

علامات اختبارات حلقة الألعاب
--type	مطلوبة: لتحديد نوع اختبار iOS الذي تريد إجراؤه. يمكنك إدخال أنواع الاختبار xctest (التلقائي) أو game-loop.
--app	مطلوبة: مسار مطلق (Google Cloud Storage أو نظام الملفات) لملف IPA الخاص بتطبيقك لا تكون هذه العلامة صالحة إلا عند تشغيل اختبارات "حلقة الألعاب".
--scenario-numbers	الحلقات (المعروفة أيضًا باسم السيناريوهات) التي تريد تنفيذها في تطبيقك: يمكنك إدخال حلقة واحدة أو قائمة أو حلقات أو نطاق من الحلقات. العدد التلقائي للحلقات هو 1. على سبيل المثال، يُجري --scenario-numbers=1-3,5 الحلقات 1 و2 و3 و5.
--device-model	الجهاز الذي تريد إجراء الاختبار عليه (يمكنك الاطّلاع على الأجهزة المتاحة التي يمكنك استخدامها).
--timeout	الحد الأقصى لمدة تنفيذ الاختبار يمكنك إدخال عدد صحيح لتمثيل المدّة بالثواني، أو عدد صحيح وعدد تسلسلي لتمثيل المدّة كوحدة زمنية أطول. على سبيل المثال: تؤدي القيمة --timeout=200 إلى إنهاء الاختبار عند تشغيله لمدة تصل إلى 200 ثانية. تؤدي القيمة --timeout=1h إلى إنهاء الاختبار عند تشغيله لمدة تصل إلى ساعة.

على سبيل المثال، يُجري الأمر التالي اختبار حلقة ألعاب ينفذ الحلقات 1 و4 و6 و7 و8 على هاتف iPhone 8 Plus:

gcloud beta firebase test ios run
 --type game-loop --app path/to/my/App.ipa --scenario-numbers 1,4,6-8
 --device-model=iphone8plus

لمزيد من المعلومات عن واجهة سطر أوامر gcloud، يُرجى الاطّلاع على المستندات المرجعية.

إجراء اختبار على الجهاز

لإجراء الاختبار على الجهاز، حمِّل تطبيق الألعاب في جهاز محاكاة ونفِّذ ما يلي:

xcrun simctl openurl SIMULATOR_UDID firebase-game-loop://

• يمكنك العثور على رقم تعريف UDID الخاص بالمحاكي من خلال تشغيل الأمر instruments -s devices.

• إذا كان هناك جهاز محاكاة واحد فقط قيد التشغيل، أدخِل السلسلة الخاصة "booted" بدلاً من SIMULATOR_UDID.

إذا كان الاختبار يتضمّن عدة حلقات، يمكنك تحديد الحلقة التي تريد تنفيذها من خلال تمرير رقم الحلقة إلى العلامة scenario. تجدر الإشارة إلى أنّه يمكنك تنفيذ حلقة واحدة فقط في كل مرة عند إجراء الاختبار على جهازك. على سبيل المثال، إذا كنت تريد تشغيل الحلقات 1 و2 و5، عليك تنفيذ أمر منفصل لكل حلقة:

xcrun simctl openurl SIMULATOR_UDID firebase-game-loop://?scenario=1
xcrun simctl openurl SIMULATOR_UDID firebase-game-loop://?scenario=2
xcrun simctl openurl SIMULATOR_UDID firebase-game-loop://?scenario=5

إنهاء اختبار مبكرًا

يستمر اختبار "حلقة الألعاب" تلقائيًا في التشغيل إلى أن يصل إلى مهلة مدتها خمس دقائق، حتى بعد تنفيذ جميع الحلقات. عند بلوغ مهلة الانتظار، ينتهي الاختبار ويلغى أي حلقات في انتظار المراجعة. يمكنك تسريع الاختبار أو إنهائه مبكرًا من خلال استدعاء مخطّط عنوان URL المخصّصTest Lab firebase-game-loop-complete في AppDelegate لتطبيقك. على سبيل المثال:

Swift

/// End the loop by calling our custom url scheme.
func finishLoop() {
    let url = URL(string: "firebase-game-loop-complete://")!
    UIApplication.shared.open(url)
}

Objective-C

- (void)finishLoop {
  UIApplication *app = [UIApplication sharedApplication];
  [app openURL:[NSURL URLWithString:@"firebase-game-loop-complete://"]
      options:@{}
completionHandler:^(BOOL success) {}];
}

يُنهي اختبار حلقة الألعاب الحلقة الحالية وينفّذ الحلقة التالية. وينتهي الاختبار عندما لا تتوفّر أيّ حلقات أخرى لتنفيذها.

كتابة نتائج اختبار مخصّصة

يمكنك ضبط اختبار Game Loop لكتابة نتائج اختبار مخصّصة في نظام ملفات جهازك. بهذه الطريقة، عندما يبدأ الاختبار، يخزِّن Test Lab ملفات النتائج في دليل GameLoopsResults على جهاز الاختبار (الذي يجب إنشاؤه بنفسك). عند انتهاء الاختبار، تنقل Test Lab جميع الملفات من دليل GameLoopResults إلى حزمة مشروعك. يُرجى مراعاة ما يلي عند إعداد الاختبار:

• يتم تحميل جميع ملفات النتائج بغض النظر عن نوع الملف أو حجمه أو كميته.

• لا تعالج أداة Test Lab نتائج الاختبار إلى أن تنتهي جميع الحلقات في الاختبار، لذا إذا كان الاختبار يتضمّن حلقات متعدّدة تكتب النتائج، تأكّد من إلحاقها بملف نتائج فريد أو إنشاء ملف نتيجة لكل حلقة. بهذه الطريقة، يمكنك تجنُّب استبدال النتائج من حلقة سابقة.

لإعداد الاختبار لكتابة نتائج اختبار مخصّصة:

1. في دليل Documents الخاص بتطبيقك، أنشئ دليلاً باسم GameLoopResults.

2. من أي مكان في رمز تطبيقك (مثل رمز المفوّض للتطبيق)، أضِف ما يلي:

   Swift

   /// Write to a results file.
   func writeResults() {
     let text = "Greetings from game loops!"
     let fileName = "results.txt"
     let fileManager = FileManager.default
     do {
   
     let docs = try fileManager.url(for: .documentDirectory,
                                    in: .userDomainMask,
                                    appropriateFor: nil,
                                    create: true)
     let resultsDir = docs.appendingPathComponent("GameLoopResults")
     try fileManager.createDirectory(
         at: resultsDir,
         withIntermediateDirectories: true,
         attributes: nil)
     let fileURL = resultsDir.appendingPathComponent(fileName)
     try text.write(to: fileURL, atomically: false, encoding: .utf8)
     } catch {
       // ...Handle error writing to file.
     }
   }
   

   Objective-C

   /// Write to a results file.
   - (void)writeResults:(NSString *)message {
       // Locate and create the results directory (if it doesn't exist already).
       NSFileManager *manager = [NSFileManager defaultManager];
       NSURL* url = [[manager URLsForDirectory:NSDocumentDirectory
                                     inDomains:NSUserDomainMask] lastObject];
       NSURL* resultsDir = [url URLByAppendingPathComponent:@"GameLoopResults"
                                                isDirectory:YES];
       [manager createDirectoryAtURL:resultsDir
         withIntermediateDirectories:NO
                          attributes:nil
                               error:nil];
   
       // Write the result message to a text file.
       NSURL* resultFile = [resultsDir URLByAppendingPathComponent:@"result.txt"];
       if ([manager fileExistsAtPath:[resultFile path]]) {
           // Append to the existing file
           NSFileHandle *handle = [NSFileHandle fileHandleForWritingToURL:resultFile
                                                                    error:nil];
           [handle seekToEndOfFile];
           [handle writeData:[message dataUsingEncoding:NSUTF8StringEncoding]];
           [handle closeFile];
       } else {
           // Create and write to the file.
           [message writeToURL:resultFile
                    atomically:NO
                      encoding:NSUTF8StringEncoding error:nil];
       }
   }