quickblox 2.23.1-beta.4 → 2.23.1-beta.5

package/__getStats-mediaType-guard-fix-plan.md

@@ -206,57 +206,69 @@ Outbound-ветка (568-581) — симметрично (`statistic.local[media
     PR, что и guard. Если откладываем — фиксируем как follow-up внутри QC-1682, без
     нового номера.
 
-## 5. Тестирование — реалистичная оценка (ВАЖНО, честно)
-
-`_getStats` — **приватная функция** (`function _getStats(...)` в модуле, НЕ на прототипе,
-НЕ экспортируется). `QB-WebRTCSpec.js` (79 строк) — **integration-тест**: реальный
-`QB.init` + `QB.chat.connect` к серверу (креды из `spec/config`), и почти всё `pending()`
-под Node (`WebRTC API isn't supported outside of the browser`). getStats там НЕ покрыт.
-
-Из этого следует: **изолированный юнит-тест на `_getStats` без вмешательства в файл
-или новой dev-зависимости невозможен**, а integration-путь требует браузера + живого
-`RTCPeerConnection` и не воспроизводит `mediaType=undefined` детерминированно. Варианты,
-что реально доступно:
-
-- **Вариант T1 (минимум, рекомендую для этого точечного guard'а):** без нового авто-теста.
-  Обоснование: правка — чистый guard + warn, не меняет поведение для валидных `mediaType`
-  (`item` существует → идентичный путь); меняет только путь `mediaType ∉ {audio,video}`
-  (раньше краш → теперь skip + traceWarning). Проверка — `lint` + существующие
-  `test:pr` (регрессия, что ничего не сломали) + ручная сверка `git diff`.
-- **Вариант T1.5 (рассмотреть, если когда-то понадобится покрытие `_getStats`):** юнит-тест
-  через `rewire` / `proxyquire` — эти библиотеки умеют доставать приватные функции из
-  модуля через `__get__` API, **не меняя production-код**. Файл `qbRTCPeerConnection.js`
-  не модифицируется, тест получает реальный `_getStats` и проверяет его на fake-peer'е
-  с `getStats: () => Promise.resolve([{ type: 'inbound-rtp', bytesReceived: 100,
-  mediaType: undefined }])`. Покрытие 100% настоящего кода без рефактора. **Цена:**
-  `rewire` — новая dev-зависимость, требует отдельного approval (CLAUDE.md DO NOT
-  запрещает `npm install` без подтверждения). **Не для этого PR**: если ставим rewire —
-  это отдельный шаг «инфраструктура тестов», не часть guard-фикса.
-- **Вариант T2 (если нужен авто-тест без новых dev-зависимостей):** вынести «нормализатор
-  одного stats-report» в чистую экспортируемую утилиту (напр.
-  `applyStatReport(statistic, result, lastResults)`), написать на неё jasmine-тест в Node
-  (без браузера) с кейсами `mediaType: 'video' | 'audio' | undefined | 'application'`.
-  Это уже **рефактор-фикс**, шире guard'а — отдельное решение пользователя (риск задеть
-  рабочий код ради тестируемости).
-
-**Рекомендация:** **T1** для самого фикса. T1.5 — кандидат на будущий PR (`mediaType ||
-kind` fallback из §4), там покрытие важнее и rewire оправдан. T2 — только если команда
-SDK хочет покрытие, но без новых dev-зависимостей.
-
-### Сравнительная таблица
-
-| Вариант | Меняет prod-код | Новые deps | Покрытие настоящего `_getStats` | Риск регрессии |
-|---|---|---|---|---|
-| T1 (рекомендую) | Нет | Нет | 0% (только lint + regression) | Минимальный |
-| T1.5 (rewire) | Нет | +rewire (требует approval) | 100% | Минимальный |
-| T2 (рефактор) | Да | Нет | 100% | Средний (риск задеть смежное) |
+## 5. Тестирование (РЕШЕНО: авто-тест на `_applyStatReport`)
+
+**СОСТОЯНИЕ на 2026-05-31 (сверено):** инфраструктура теста уже готова другим агентом —
+тестировать решено через выделенную функцию `_applyStatReport`, БЕЗ новых dev-зависимостей
+(rewire не нужен):
+- `qbRTCPeerConnection._applyStatReport = _applyStatReport;` (строка **832**) — функция
+  экспонирована как статик-свойство модуля. Чистая, синхронная, без сети/браузера.
+- Создан спек `spec/QB-WebRTCStatsSpec.js` (113 строк) — `require` модуля напрямую под
+  Node, `apply = RTCPeerConnection._applyStatReport`, `freshStatistic()` хелпер.
+- Спек **зарегистрирован во всех 3 jasmine-конфигах** (`jasmine.json`, `jasmine.pr.json`,
+  `jasmine.full.json`) → подхватывается `npm test` и `npm run test:pr`.
+
+**Уже покрыто (6 кейсов, guard-часть):** inbound video, inbound audio, `mediaType=undefined`
+(не бросает, remote не мутируется), `mediaType='application'` (skip), outbound video
+(симметрия), `remote-candidate` (рефактор не сломал candidate-ветку).
+
+### ОСТАЛОСЬ ДОБАВИТЬ — кейсы на `kind`-fallback (сердцевина варианта 1)
+
+Текущий тест НЕ проверяет fallback (его в коде ещё нет). После добавления fallback (§4)
+дописать в `QB-WebRTCStatsSpec.js`:
+
+1. **Safari inbound video — `kind` без `mediaType`:**
+   ```js
+   it('fills statistic.remote.video when only kind is present (Safari)', function() {
+     var statistic = freshStatistic();
+     apply(statistic, {
+       type: 'inbound-rtp', kind: 'video', mediaType: undefined,
+       bytesReceived: 1000, packetsReceived: 10, timestamp: 12345
+     }, null);
+     expect(statistic.remote.video.bytesReceived).toEqual(1000);
+   });
+   ```
+2. **Safari inbound audio — `kind` без `mediaType`** (аналогично, `kind:'audio'`,
+   проверить `statistic.remote.audio.bytesReceived`).
+3. **Safari outbound video — `kind` без `mediaType`** (`type:'outbound-rtp'`, `kind:'video'`,
+   `bytesSent`, проверить `statistic.local.video.bytesSent`).
+4. **Приоритет `mediaType` над `kind`** (на случай конфликта): `mediaType:'video'`,
+   `kind:'audio'` → пишется в `remote.video` (т.к. `mediaType || kind` → `mediaType`).
+   Защищает от регрессии, если кто-то поменяет порядок на `kind || mediaType`.
+5. **Ни `mediaType`, ни `kind`** → skip, не бросает, remote не мутируется
+   (этот кейс частично есть как `mediaType=undefined`, но без `kind` — дополнить, что и
+   `kind` отсутствует, чтобы fallback тоже резолвился в `undefined`).
+6. **(желательно) framerate на Safari:** inbound `kind:'video'`, `framerateMean: 30`,
+   `lastResults` с предыдущим timestamp → `statistic.remote.video.framesPerSecond`
+   заполнен. Это прямая проверка, что нормализация `mediaType` в переменную (см. §4)
+   починила и framerate-ветку, а не только индексацию.
+
+### Замечание по browser-ветке спека (не блокер для PR)
+
+Строка 9 спека: `window.QB.webrtc.RTCPeerConnection` — путь для браузер-прогона. Под Node
+(`isNodeEnv=true`, как в `test:pr`) не используется. Перед браузер-прогоном стоит
+подтвердить, что `QB.webrtc.RTCPeerConnection` — реальный публичный путь; для PR-проверки
+(Node) не критично.
 
 ## 6. Сборка / проверка (клон 05)
 
 `node_modules` на месте — `npm i` не требуется. Скрипты (из package.json):
-1. `git diff` — только строки 547-564 (2 блока).
+1. `git diff` — функция `_applyStatReport` в `qbRTCPeerConnection.js` (+ статик-экспорт стр.
+   832) + спек `spec/QB-WebRTCStatsSpec.js`. Финальная правка добавит лишь `kind`-fallback
+   к функции и fallback-кейсы в спек.
 2. `npm run lint` (jshint) — должно быть чисто.
-3. `npm run test:pr` (jasmine PR-набор, включает `QB-WebRTCSpec.js`) — регрессия зелёная.
+3. `npm run test:pr` (jasmine PR-набор, включает `QB-WebRTCSpec.js` + `QB-WebRTCStatsSpec.js`)
+   — все кейсы зелёные (6 guard + новые fallback).
 4. (опц.) `npm run test:node-regression` (`spec/phase-a-upgrade-check.js`).
 5. `npm run build` НЕ обязателен для PR кода (dist собирается отдельно), но если нужен
    собранный артефакт для проверки на проекте — `npm run build` (lint+gulp+minify).
@@ -296,12 +308,13 @@ SDK хочет покрытие, но без новых dev-зависимост
   Safari-статистику (QC-1645/QC-1475). Оба в одном `[QC-1682]`-PR. Guard уже в коде;
   остался fallback (§4).
 
-**ОТКРЫТО (нужно решение перед финальной правкой):**
-1. **Авто-тест на `_applyStatReport`?** Функция уже выделена другим агентом, поэтому
-   юнит-тест без новых dev-зависимостей теперь возможен (jasmine, Node): передать
-   fake-`statistic` + fake-`result` с разными `mediaType`/`kind`, проверить заполнение и
-   skip. Варианты: **T-да** (написать тест — рекомендую, раз функция уже тестопригодна) /
-   **T-нет** (только lint+test:pr регрессия). Цена T-да минимальна (функция чистая).
+- **Авто-тест — РЕШЕНО: ДА.** Через `_applyStatReport` (статик `qbRTCPeerConnection._applyStatReport`,
+  строка 832), спек `spec/QB-WebRTCStatsSpec.js` уже создан и зарегистрирован в jasmine-конфигах.
+  Guard-кейсы (6) уже написаны; остаётся дописать `kind`-fallback-кейсы (см. §5, 6 шт.).
+
+**Открытых вопросов перед кодом не осталось.** Оставшаяся работа агента:
+(1) `kind`-fallback в `_applyStatReport` (§4), (2) fallback-тест-кейсы (§5), (3) lint +
+test:pr, (4) подготовить текст коммита `[QC-1682]` для пользователя.
 
 ## 9. Доставка фикса до прода — вариант A (РЕШЕНО 2026-05-30)
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "quickblox",
   "description": "QuickBlox JavaScript SDK",
-  "version": "2.23.1-beta.4",
+  "version": "2.23.1-beta.5",
   "homepage": "https://quickblox.com/developers/Javascript",
   "main": "src/qbMain.js",
   "types": "quickblox.d.ts",

package/quickblox.js

@@ -36938,34 +36938,38 @@ function _getStats(peer, lastResults, successCallback, errorCallback) {
 
 function _applyStatReport(statistic, result, lastResults) {
     var item;
+    // mediaType is deprecated in the W3C webrtc-stats spec and replaced by kind.
+    // Safari/WebKit omits mediaType on some reports and provides only kind, so we
+    // normalize once and use it for both the statistic lookup and the 'video' check.
+    var mediaType = result.mediaType || result.kind;
 
     if (result.bytesReceived && result.type === 'inbound-rtp') {
-        item = statistic.remote[result.mediaType];
+        item = statistic.remote[mediaType];
 
         if (item) {
             item.bitrate = _getBitratePerSecond(result, lastResults, false);
             item.bytesReceived = result.bytesReceived;
             item.packetsReceived = result.packetsReceived;
             item.timestamp = result.timestamp;
-            if (result.mediaType === 'video' && result.framerateMean) {
+            if (mediaType === 'video' && result.framerateMean) {
                 item.framesPerSecond = Math.round(result.framerateMean * 10) / 10;
             }
         } else {
-            Helpers.traceWarning('_getStats: skipping inbound-rtp report with unknown mediaType: ' + result.mediaType);
+            Helpers.traceWarning('_getStats: skipping inbound-rtp report with unknown mediaType/kind: ' + mediaType);
         }
     } else if (result.bytesSent && result.type === 'outbound-rtp') {
-        item = statistic.local[result.mediaType];
+        item = statistic.local[mediaType];
 
         if (item) {
             item.bitrate = _getBitratePerSecond(result, lastResults, true);
             item.bytesSent = result.bytesSent;
             item.packetsSent = result.packetsSent;
             item.timestamp = result.timestamp;
-            if (result.mediaType === 'video' && result.framerateMean) {
+            if (mediaType === 'video' && result.framerateMean) {
                 item.framesPerSecond = Math.round(result.framerateMean * 10) / 10;
             }
         } else {
-            Helpers.traceWarning('_getStats: skipping outbound-rtp report with unknown mediaType: ' + result.mediaType);
+            Helpers.traceWarning('_getStats: skipping outbound-rtp report with unknown mediaType/kind: ' + mediaType);
         }
     } else if (result.type === 'local-candidate') {
         item = statistic.local.candidate;
@@ -39719,7 +39723,7 @@ module.exports = StreamManagement;
  */
 
 var config = {
-  version: '2.23.1-beta.4',
+  version: '2.23.1-beta.5',
   buildNumber: '1179',
   creds: {
     'appId': 0,