Αυτοματοποιημένες δοκιμές και επαλήθευση

Οι αυτοματοποιημένες δοκιμές επαληθεύουν κώδικα και περιεχόμενο Defold με ρητά, μηχανικώς αναγνώσιμα αποδεικτικά στοιχεία. Χρησιμοποιήστε αυτό το εγχειρίδιο για να σχεδιάσετε δοκιμές που λειτουργούν εξίσου με τοπικά σενάρια, εκτελεστές CI (Συνεχούς Ενσωμάτωσης) και πράκτορες προγραμματισμού. Καλύπτει δοκιμές αρθρωμάτων, συλλογές που εκτελούνται, δοκιμές προγράμματος περιήγησης, αυτοματισμό χρόνου εκτέλεσης, οπτικούς ελέγχους, δημιουργίες χωρίς γραφικό περιβάλλον και παρέχει χρήσιμες καλές πρακτικές.

Επίπεδα επαλήθευσης

Τα κατάλληλα επίπεδα αυτοματοποιημένων δοκιμών ακολουθούν το πλαίσιο της πυραμίδας δοκιμών, το οποίο χωρίζει τις δοκιμές σε τρία κύρια στρώματα: δοκιμές μονάδας, δοκιμές ενσωμάτωσης και δοκιμές από άκρο σε άκρο (E2E). Στο Defold μπορείτε να διαχωρίζετε τις δοκιμές σε συγκεκριμένες συλλογές που μπορούν να φορτώνονται κατά την εκκίνηση. Συνήθως είναι καλό να ξεκινάτε με τον στενότερο και ταχύτερο έλεγχο που μπορεί να εντοπίσει το πρόβλημα και έπειτα να προσθέτετε δοκιμές χρόνου εκτέλεσης ή πλατφόρμας όπου χρειάζεται.

Μια επιτυχής μεταγλώττιση αποδεικνύει ότι το έργο δημιουργείται, αλλά δεν αποδεικνύει τη σωστή συμπεριφορά του παιχνιδιού. Ένα στιγμιότυπο οθόνης δεν αποδεικνύει σύνθετες μεταβάσεις, κινούμενα σχέδια, αλληλεπιδράσεις ή τη ροή του παιχνιδιού, αλλά μπορεί να χρησιμοποιηθεί από σύγχρονες πολυτροπικές λύσεις για την επιθεώρηση της εμφάνισης ενός καρέ και του κατά πόσο οι shaders και η οπτική διάταξη είναι σωστά. Ωστόσο, για αυτοματοποιημένες δοκιμές προτιμήστε ντετερμινιστικούς ισχυρισμούς όταν η συνθήκη μπορεί να εκφραστεί άμεσα.

Επαναχρησιμοποιήσιμος και ελέγξιμος κώδικας Lua

Διατηρήστε την επαναχρησιμοποιήσιμη λογική σε αρθρώματα Lua με ελάχιστες εξαρτήσεις από τη μηχανή. Οι αμιγείς μετασχηματισμοί δεδομένων, οι κανόνες, οι μηχανές καταστάσεων και οι υπολογισμοί μπορούν έτσι να ελεγχθούν χωρίς την κατασκευή ενός πλήρους κόσμου παιχνιδιού.

Διαχωρίστε τον κώδικα που επικοινωνεί με τη μηχανή από τη λογική που καλεί. Ένα σενάριο μπορεί να μετατρέπει μηνύματα και κατάσταση συστατικών σε κλήσεις προς ένα άρθρωμα, ενώ οι δοκιμές καλούν απευθείας το άρθρωμα με ελεγχόμενες εισόδους.

Δείτε το εγχειρίδιο Συγγραφής κώδικα για περισσότερες λεπτομέρειες.

Δοκιμές σε μια συλλογή που εκτελείται

Χρησιμοποιήστε μια ειδική συλλογή δοκιμών όταν η συμπεριφορά εξαρτάται από αντικείμενα παιχνιδιού, συστατικά, μηνύματα, είσοδο, φυσική ή άλλα συστήματα της μηχανής.

Κάθε δοκιμή θα πρέπει:

1. να καθιερώνει μια γνωστή κατάσταση,
2. να εκτελεί μία συμπεριφορά,
3. να ελέγχει και να αξιολογεί το αναμενόμενο αποτέλεσμα,
4. να καθαρίζει τους πόρους που δημιουργήθηκαν,
5. να εκπέμπει μια δομημένη περιγραφή αποτελέσματος.

Προτιμήστε απομονωμένες συλλογές δοκιμών. Ένα έργο μπορεί να επιλέξει μια συλλογή εκκίνησης δοκιμών μέσω μιας προσωρινής ρύθμισης έργου στο game.project:

[bootstrap]
main_collection = /test/test.collectionc

Μην αφήνετε μια προσωρινή συλλογή εκκίνησης δοκιμών στην κανονική διαμόρφωση του έργου. Στο CI, προτιμήστε ένα ειδικό αρχείο ρυθμίσεων που μεταβιβάζεται στο Bob. Το CI δεν μπορεί να αλλάζει την κατάσταση του αποθετηρίου και θα πρέπει να κάνει μόνο προσωρινές αλλαγές όταν χρειάζεται.

Για σύνθετα παιχνίδια, μπορείτε να δημιουργήσετε μικρές συλλογές «χώρων ανάπτυξης» με προκαθορισμένα σενάρια και απλά προσχέδια. Καθιστούν τους μηχανισμούς αναπαραγώγιμους και διευκολύνουν την ανάπτυξη και τις δοκιμές χωρίς περιήγηση σε άσχετες καταστάσεις και ενότητες του παιχνιδιού.

Πλαίσια δοκιμών

Τα έργα μπορούν να υλοποιούν έναν μικρό εκτελεστή ή να χρησιμοποιούν μια βιβλιοθήκη δοκιμών της κοινότητας.

Για παράδειγμα, το DefTest είναι μια βιβλιοθήκη δοκιμών μονάδας που βασίζεται στο Telescope. Υποστηρίζει σουίτες, συναρτήσεις ρύθμισης και αποδόμησης, ισχυρισμούς, φιλτράρισμα ονομάτων, απομιμήσεις για επιλεγμένα API του Defold και προαιρετική κάλυψη LuaCov. Οι δοκιμές μπορούν να εκτελούνται από μια ειδική συλλογή εκκίνησης, ακόμη και σε ένα πακέτο χωρίς γραφικό περιβάλλον που δημιουργήθηκε με το Bob.

Δομημένα αποτελέσματα δοκιμών

Η σύνοψη κονσόλας ή αρχείου καταγραφής ενός πλαισίου μπορεί να είναι χρήσιμη στους προγραμματιστές, αλλά ένας μη επιβλεπόμενος αυτόματος ελεγκτής χρειάζεται και πάλι ένα ρητό αποτέλεσμα ολοκλήρωσης. Αν χρειάζεται, προσθέστε έναν μικρό προσαρμογέα γύρω από την επανάκληση ή τη σύνοψη του πλαισίου, ώστε ο ελεγκτής να επεξεργάζεται εύκολα τα αποτελέσματα των δοκιμών.

Μια απλή περιγραφή αποτελεσμάτων μπορεί να χρησιμοποιεί ένα μοναδικό πρόθεμα, ακολουθούμενο από ένα αντικείμενο JSON σε κάθε φυσική γραμμή της κονσόλας:

TEST {"run":"8f13","event":"suite_start","tests":2}
TEST {"run":"8f13","event":"case","name":"player_moves","status":"pass","duration_ms":3}
TEST {"run":"8f13","event":"case","name":"player_stops","status":"pass","duration_ms":2}
TEST {"run":"8f13","event":"suite_end","status":"pass","passed":2,"failed":0}

Ένας συλλέκτης θα πρέπει να επεξεργάζεται κάθε γραμμή ανεξάρτητα, να εντοπίζει το πρόθεμα TEST, να αναλύει το JSON που ακολουθεί και να αγνοεί τη μη σχετική έξοδο της μηχανής.

Συμπεριλάβετε ένα μοναδικό αναγνωριστικό εκτέλεσης, ώστε η έξοδος από μια παλιά ή ταυτόχρονη διεργασία να μην μπορεί να ολοκληρώσει την τρέχουσα εκτέλεση. Κάθε σουίτα θα πρέπει να εκπέμπει ένα σαφές τελικό συμβάν (όπως Pass, Failure, Crash, Timeout κ.λπ.).

Συλλογή εξόδου κονσόλας

Όταν ένα παιχνίδι εκτελείται από τον επεξεργαστή, παρέχει τόσο το τρέχον ιστορικό κονσόλας όσο και μια συνεχή ροή. Κλείστε τη ροή μετά από ένα αντίστοιχο συμβάν ολοκλήρωσης σουίτας, τον τερματισμό της διεργασίας, ένα σφάλμα ή τη συμπλήρωση ενός ρυθμισμένου χρονικού ορίου ή ορίου γραμμών.

Διαβάστε περισσότερα στο εγχειρίδιο Editor HTTP API.

Μόνιμα αρχεία καταγραφής

Το Defold μπορεί επίσης να αποθηκεύει το αρχείο καταγραφής του παιχνιδιού ενεργοποιώντας το Write Log File στο game.project. Δείτε τα Αρχεία καταγραφής παιχνιδιού και συστήματος. Η καταγραφή σε αρχείο είναι χρήσιμη για πακεταρισμένες εφαρμογές και για τη δοκιμή συσκευών-στόχων στις οποίες η κονσόλα του επεξεργαστή δεν είναι διαθέσιμη.

Το έργο μπορεί να χρησιμοποιεί τις ενσωματωμένες συναρτήσεις print() και pprint() ή, π.χ., οποιαδήποτε άλλη βιβλιοθήκη καταγραφής από την Πύλη Πόρων μας.

Δοκιμή ενός παιχνιδιού που εκτελείται μέσω API χρόνου εκτέλεσης

Ένα API αυτοματισμού χρόνου εκτέλεσης μπορεί να επιθεωρεί και να ελέγχει μια ζωντανή δοκιμαστική μηχανή. Μπορεί να χρησιμοποιηθεί όταν οι δοκιμές πρέπει να εντοπίζουν αντικείμενα χρόνου εκτέλεσης, να εισάγουν είσοδο, να περιμένουν μια ορατή κατάσταση ή να καταγράφουν το αποδιδόμενο αποτέλεσμα.

Διαβάστε το εγχειρίδιο υπηρεσίας μηχανής για περισσότερες λεπτομέρειες.

Το παρακάτω παράδειγμα χρησιμοποιεί τη δομή του βοηθητικού Python του Automation Bridge. Το έργο πρέπει να περιλαμβάνει μια συμβατή έκδοση της δοκιμαστικής επέκτασης, να εκθέτει ένα στοιχείο με το δεδομένο αναγνωριστικό αυτοματισμού και να δημοσιεύει την κατάσταση εφαρμογής screen:

from automation_bridge import editor

project = editor.open_project(".")
game = project.build_and_run()

try:
    play = game.element(automation_id="play_button")
    game.click(play)
    game.wait_for_state("screen", "gameplay", timeout=5.0)
    screenshot = game.screenshot()
    print(screenshot.path)
finally:
    game.close_engine()

Οι καταστάσεις που ορίζονται από την εφαρμογή και τα αναγνωριστικά αυτοματισμού χρησιμοποιούν το προαιρετικό API Lua μόνο για δοκιμαστικές εκδόσεις του Automation Bridge, το οποίο πρέπει να ενεργοποιεί και να δημοσιεύει το έργο. Μια σταθερή παύση είναι ευάλωτη στην ταχύτητα του μηχανήματος και στον χρονισμό των καρέ· η οριοθετημένη περιοδική διερεύνηση για μια καθορισμένη κατάσταση είναι πιο αξιόπιστη.

Το Automation Bridge είναι επέκταση και όχι μέρος του πυρήνα της μηχανής. Συμβουλευτείτε την αναφορά Python API για τους επιλογείς, τις αναμονές, την κατάσταση, τα συμβάντα, τα στιγμιότυπα οθόνης και τα διαγνωστικά στοιχεία της εγκατεστημένης έκδοσης.

Δοκιμές προγράμματος περιήγησης για HTML5

Ο επεξεργαστής μπορεί να δημιουργήσει και να διαθέσει μια δημιουργία HTML5 μέσω της τρέχουσας εντολής build-html5, όπως περιγράφεται στο εγχειρίδιο Editor HTTP API. Το Bob μπορεί επίσης να δημιουργήσει ένα πακέτο HTML5 χωρίς τον επεξεργαστή.

Εξωτερικά εργαλεία αυτοματισμού προγράμματος περιήγησης, όπως τα Playwright, Puppeteer, Selenium, WebdriverIO ή Cypress, μπορούν:

• να περιμένουν τον καμβά Defold και την ετοιμότητα της εφαρμογής,
• να στέλνουν είσοδο πληκτρολογίου, ποντικιού και εξομοιωμένης αφής,
• να αλλάζουν το μέγεθος της περιοχής προβολής,
• να συλλέγουν έξοδο κονσόλας του προγράμματος περιήγησης και σφάλματα JavaScript,
• να λαμβάνουν στιγμιότυπα οθόνης και να συγκρίνουν παραδοτέα.

Η είσοδος που κατευθύνεται στον καμβά επεξεργάζεται μέσω των κανονικών συνδέσεων εισόδου του έργου και των επανακλήσεων on_input(). Δοκιμάστε τόσο την απόκριση του παιχνιδιού όσο και τα σημεία ενσωμάτωσης που αφορούν το πρόγραμμα περιήγησης.

Η πιο αξιόπιστη προσέγγιση είναι να εκθέσετε μια ρητή γέφυρα δοκιμών JavaScript στο προσαρμοσμένο index.html. Στην πλευρά του Defold, οι δημιουργίες HTML5 μπορούν να εκτελούν JavaScript με τη χρήση του html5.run(), γεγονός που καθιστά δυνατή την επικοινωνία με μια τέτοια γέφυρα στην πλευρά του προγράμματος περιήγησης. Για εντολές που μεταφέρονται από τη JavaScript πίσω στο Defold, χρησιμοποιήστε μια ειδική γέφυρα JavaScript προς μηχανή.

Διατηρήστε τις δοκιμές προγράμματος περιήγησης οριοθετημένες. Διακρίνετε μια αποτυχία φόρτωσης σελίδας, έναν καμβά που λείπει, ένα σφάλμα JavaScript, ένα χρονικό όριο δοκιμής και έναν αποτυχημένο ισχυρισμό του παιχνιδιού στην τελική αναφορά.

Προεπισκοπήσεις επεξεργαστή και στιγμιότυπα οθόνης χρόνου εκτέλεσης για οπτική επιθεώρηση

Μπορείτε να δημιουργήσετε στιγμιότυπο οθόνης των αρχείων πόρων στην προεπιλεγμένη προβολή σκηνής του ανοιχτού επεξεργαστή ή ενός παιχνιδιού κατά τον χρόνο εκτέλεσης.

Μπορείτε να χρησιμοποιείτε σύγκριση εικόνων, π.χ. για δοκιμές παλινδρόμησης. Αποθηκεύστε την εικόνα διαφορών και τις μετρικές σύγκρισης όταν αποτυγχάνει ένας έλεγχος.

Ένα πολυτροπικό μοντέλο μπορεί να αξιολογήσει στην οπτική επιθεώρηση σημασιολογικές συνθήκες που είναι δύσκολο να εκφραστούν διαφορετικά, όπως αποκομμένο κείμενο, επικαλυπτόμενα στοιχεία ελέγχου, ασαφείς καταστάσεις επιλογής ή περιεχόμενο εκτός μιας ασφαλούς περιοχής. Συνιστάται να αντιμετωπίζετε αυτή την αξιολόγηση ως πρόσθετο σήμα με ρητά κριτήρια, αλλά όχι ως υποκατάστατο ντετερμινιστικών ελέγχων λογικής ή σύγκρισης εικόνων.

Δοκιμές χωρίς γραφικό περιβάλλον και CI

Χρησιμοποιήστε το εργαλείο δημιουργίας Bob CLI για CI ανεξάρτητο από τον επεξεργαστή.

Μπορείτε να το χρησιμοποιήσετε για να επιλύσετε εξαρτήσεις, να δημιουργήσετε ένα παιχνίδι, ένα αρχείο ή ένα αυτόνομο πακέτο και να δημιουργήσετε μια αναφορά JSON:

mkdir -p build/reports

java -jar bob.jar \
  --root . \
  --archive \
  --build-report-json build/reports/build-report.json \
  resolve build

Δημιουργήστε ένα πακέτο δοκιμών χωρίς γραφικό περιβάλλον με ειδικές ρυθμίσεις:

java -jar bob.jar \
  --root . \
  --settings test/test.settings \
  --platform x86_64-linux \
  --variant headless \
  --archive \
  --bundle-output build/test-bundle \
  resolve build bundle

Εκτελέστε το εκτελέσιμο αρχείο που προκύπτει με έναν ελεγκτή διεργασιών κατάλληλο για την πλατφόρμα. Καταγράψτε την κατάσταση εξόδου και τα αρχεία καταγραφής του, επιβάλετε χρονικό όριο και απαιτήστε το δομημένο συμβάν ολοκλήρωσης της σουίτας.

Το εγχειρίδιο Bob περιγράφει πλατφόρμες, αρχεία ρυθμίσεων, πακέτα, προσωρινές μνήμες, εγγενείς επεκτάσεις και αναφορές δημιουργίας.

Αναφορές αποτυχίας και παραδοτέα

Τα σωστά αποτελέσματα δοκιμών θα πρέπει να διατηρούν αρκετά αποδεικτικά στοιχεία για την αναπαραγωγή και τη διάγνωση μιας αποτυχίας:

• όνομα δοκιμής, αναγνωριστικό εκτέλεσης και λεπτομέρειες ισχυρισμού,
• χρόνος που παρήλθε και ταξινομημένο αποτέλεσμα,
• πλήρες αρχείο καταγραφής κονσόλας ή διεργασίας,
• έκδοση Defold, πλατφόρμα-στόχος και σχετική διαμόρφωση,
• αναφορά δημιουργίας Bob και κατάσταση εξόδου διεργασίας,
• κατάσταση χρόνου εκτέλεσης ή στιγμιότυπο σκηνής, όταν είναι διαθέσιμο,
• στιγμιότυπα οθόνης, διαφορές από τη γραμμή βάσης, εγγραφές ή ίχνη προγράμματος περιήγησης,
• διαδρομές ή συνδέσμους προς όλα τα παραχθέντα παραδοτέα.

Η ίδια μορφή θα πρέπει να μπορεί να χρησιμοποιηθεί από έναν προγραμματιστή, ένα τοπικό σενάριο, μια υπηρεσία CI ή έναν πράκτορα προγραμματισμού AI. Έτσι η επαλήθευση παραμένει ντετερμινιστική ακόμη και όταν η διάγνωση ή η επιδιόρθωση ανατίθεται.