Англійська для розробників Puppeteer

Вади лялькаря часто є вадами часу, що носять маску — тест, який «випадково провалюється», зазвичай є перегонами між сценарієм і сторінкою, а не справжньою випадковістю. Назвавши це точно, замість того, щоб називати це “плисковим”, ми насправді вирішимо ці проблеми, а не просто повторимо спробу.

---

Браузер і сторінка

** Безголовий режим ** — запуск переглядача без видимого інтерфейсу користувача, швидший і підходящий для CI, на відміну від режиму « головного », у якому ви можете спостерігати за діями переглядача у реальному часі для зневадження.

“Запустіть його локально з головкою, поки ви зневаджуєте це — безголовковий режим приховує саме ту проблему відтворення, яку ви шукаєте.”

** Сторінка ** — один екземпляр вкладки або вікна, яким керує Puppeteer, об’ єкт, з яким безпосередньо взаємодіє більшість коду автоматизації.

“Не використовувати один і той же об’ єкт сторінки для неспоріднених тестів — створювати нову сторінку для кожного тесту, щоб стан не витікав між ними.”

** page.evaluate() ** — запуск JavaScript у контексті сторінки (переглядач, а не вузол), використовується для читання стану DOM або виклику поведінки на сторінці, яку API Puppeteer не виявляє безпосередньо.

“Ви не можете прочитати це значення з Node безпосередньо — обгорніть його в page.evaluate(), щоб воно працювало всередині контексту сторінки.”

---

Час і місце

** Селектор ** — рядок (CSS або XPath), який визначає один або декілька елементів на сторінці, що є основою для більшості взаємодій, таких як клацання і видобування тексту.

“Цей селектор занадто широкий — він відповідає трьом елементам, і Puppeteer натискає той, який знаходиться першим у DOM.”

** Перегони (у автоматизації) ** — коли скрипт намагається взаємодіяти з елементом до того, як сторінка закінчить відтворення або оновлення, що призведе до періодичних помилок, залежно від часу.

• “Це не є тріщинами у випадковому сенсі — це перегони між клацання і модальної анімації завершення.” *

** Явно очікувати ** — навмисне очікування на певну умову (появу елемента, завершення мережевого запиту, завершення навігації) перед продовженням, замість фіксованої затримки.

“Замініть waitForTimeout(2000) явним чеканням на селектор — фіксоване затримання або марнує час, або недостатньо довге, залежно від машини.”

---

Надійність і зневадження

** Флакі- тест ** — тест, який проходить і провалюється періодично у незмінному коді, майже завжди спричинено не обробленим умовою гонки, а не справжньою випадковістю.

“Перед тим, як ми поставимо його на карантин, давайте підтвердимо, що це насправді лускатий, а не просто стан раси, який ми ще не знайшли.” *

** Знімок екрана diff (візуальна регресія) ** — порівнює знятий знімок з базовим зображенням для виявлення небажаних візуальних змін, які відрізняються від функціональних тверджень.

• « Функціональний тест пройдено, але на знімку вікна diff виявлено, що кнопка пересунулася на три пікселі після цієї зміни CSS. » *

** Бездіяльність мережі ** — стан очікування, що означає, що у визначеному вікні не було виконано жодного мережевого запиту. Цей параметр використовується для переконання, що сторінка завершила завантаження асинхронного вмісту перед тим, як з нею буде взаємодіяти.

“Зачекайте, поки мережа не буде бездіяльною перед переглядом цієї сторінки — це викликає фоновий запит, який заповнює половину вмісту.”

---

Поширені помилки

• Називати кожну періодичну помилку “флаком” без підтвердження, що це справжня гонка проти реальної, відтворюваної помилки на самій сторінці.
• Досягнення фіксованого waitForTimeout() замість явного очікування, що або сповільнює набір або все ще не вдається під навантаженням.
• Запис надто широкого селектора, який працює сьогодні, але беззвучно починає відповідати неправильному елементу після не пов’ язаної зі зміною розмітки.

Практичні вправи

1. Поясніть, у двох реченнях, різницю між тестом з тріщинами і по- справжньому відтворюваною вадами.
2. Написати короткий коментар PR, у якому рекомендується явно зачекати замість фіксованого часу очікування у новому тесті.
3. Створити проект повідомлення, у якому буде пояснено співробітнику команди, чому широкий селектор CSS є ймовірною причиною неодноразових помилок при клацанні.

Зв’язані ресурси

• Англійська для швидких розробників
• Англійська мова для розробників історичних книг
• Англійська для розробників

Наприклад, англ. Beyond the Basics

Основний словник Puppeteer – такі терміни як «безголовий», «вибір», «оцінка» і «фломастер» – є необхідними. Але справжній досвідчений розробник повинен розуміти * як* ці слова використовуються у професійному спілкуванні, особливо при співпраці з міжнародними командами. Не достатньо просто знати, що означає « тріщини »; вам потрібно зрозуміти тонкі наслідки опису тесту як такий, і як це впливає на очікування і стратегії зневадження. Критична відмінність часто виникає з різних культурних підходів до вирішення проблем - деякі культури цінують прямоту, в той час як інші надають пріоритет детальному поясненню. Навчання точності у формулюванні ваших запитів і відгуків зменшить кількість непорозумінь і сприяє продуктивнішому співробітництву. Розгляньте контекст: випадкове повідомлення Slack, яке обговорює незначну візуальну помилку, потребує іншого тону, ніж формальне повідомлення про перегляд коду, яке стосується значної проблеми з продуктивністю. Крім того, розуміння * чому * за певними практиками - наприклад, чому ми можемо навмисно використовувати більш специфічні селекторів - так само важливо, як знати * як * реалізувати їх. Це стосується будівництва спільного розуміння і встановлення чітких протоколів комунікації в межах вашої команди. Не бійтеся задати питання, щоб прояснити ситуацію; набагато краще шукати пояснення, ніж робити припущення, які можуть призвести до марного часу і розчарування.

Однією з ключових областей, де це часто проявляється, є опис поведінки самих тестів. Сказать, что тест провалился, недостаточно. Розробник з, скажімо, Німеччини може очікувати детального пояснення * чому * він зазнав невдачі, включаючи конкретні журнали, мережеві запити і знімок екрана. Аналогічно, колега з Японії може оцінити покрокове розбиття дій, які здійснює тестовий бігун. Цей рівень деталізації є критичним для ефективного зневадження, особливо коли мова йде про складні взаємодії з переглядачем. Це також проактивне управління очікуваннями. Коли ви визначаєте потенційну проблему — навіть якщо це лише невелика затримка — чітке повідомлення про це * перед * тестовими запусками може запобігти небажаній тривозі і дозволити проактивні стратегії зменшення. Нарешті, пам’ ятайте, що документація не обмежується лише технічними специфікаціями; чітке спілкування у вашій команді функціонує як власна форма документації.

Розглянемо такий сценарій: ви переглядаєте PR, надісланий колегою з Бразилії, який реалізував нову функцію за допомогою Puppeteer. Набір тестів містить тест, пов’ язаний з динамічним елементом на сторінці. Замість того, щоб просто прокоментувати « Цей тест не працює », що можна розглядати як критику, ви можете сказати щось на зразок: « Я помітив, що цей тест періодично зазнає невдачі під час завантаження сторінки з описом продукту. Можемо ми розслідувати час виклику evaluate? Можливо, збільшення інтервалу опитування або додавання невеликої затримки перед твердженням забезпечило б більшу стабільність». Цей підхід визнає проблему, надає контекст і пропонує конкретну область для дослідження – всі важливі елементи конструктивного зворотнього зв’язку.

// Example: Using Puppeteer to pause execution for debugging flaky tests.
const puppeteer = require('puppeteer');

(async () => {
  const browser = await puppeteer.launch({ headless: false }); // For visual debugging
  const page = await browser.newPage();
  await page.goto('https://www.example.com'); 
  // Simulate a flaky interaction (e.g., waiting for an element to load)
  await page.waitForTimeout(500); // Pause execution for 500ms - useful for debugging
  console.log("Test paused for debugging");
  await browser.close();
})();

Сфокусувавшись на точній мові і обдуманому спілкуванні, ви не тільки поліпшитимете свої технічні навички з Puppeteer, але і побудуєте міцніші стосунки з вашою глобальною командою розробників.