Trigger ATTACH_MEDIA_ERROR when calling attachMedia with falsey media argument (#6556)

Resolves #6463

Author: agajassi

api-extractor/report/hls.js.api.md

@@ -1054,6 +1054,8 @@ export interface ErrorData {
 //
 // @public (undocumented)
 export enum ErrorDetails {
+    // (undocumented)
+    ATTACH_MEDIA_ERROR = "attachMediaError",
     // (undocumented)
     AUDIO_TRACK_LOAD_ERROR = "audioTrackLoadError",
     // (undocumented)

src/errors.ts

@@ -85,6 +85,8 @@ export enum ErrorDetails {
   INTERNAL_EXCEPTION = 'internalException',
   // Identifier for an internal call to abort a loader
   INTERNAL_ABORTED = 'aborted',
+  // Triggered when attachMedia fails
+  ATTACH_MEDIA_ERROR = 'attachMediaError',
   // Uncategorized error
   UNKNOWN = 'unknown',
 }

src/hls.ts

@@ -389,6 +389,17 @@ export default class Hls implements HlsEventEmitter {
    * Attaches Hls.js to a media element
    */
   attachMedia(media: HTMLMediaElement) {
+    if (!media) {
+      const error = new Error(`attachMedia failed: media argument is ${media}`);
+      this.trigger(Events.ERROR, {
+        type: ErrorTypes.OTHER_ERROR,
+        details: ErrorDetails.ATTACH_MEDIA_ERROR,
+        fatal: true,
+        error,
+      });
+      return;
+    }
+
     this.logger.log('attachMedia');
     this._media = media;
     this.trigger(Events.MEDIA_ATTACHING, { media: media });

tests/unit/hls.ts

@@ -1,9 +1,11 @@
 import Hls from '../../src/hls';
 import { hlsDefaultConfig } from '../../src/config';
 import { Events } from '../../src/events';
+import { ErrorTypes, ErrorDetails } from '../../src/errors';
 
 import chai from 'chai';
 import sinonChai from 'sinon-chai';
+import sinon from 'sinon';
 
 chai.use(sinonChai);
 const expect = chai.expect;
@@ -51,7 +53,8 @@ describe('Hls', function () {
         );
       });
     }
-    it('should add and remove refrences to the "media" element immediately', function () {
+
+    it('should add and remove references to the "media" element immediately', function () {
       const hls = new Hls({ capLevelOnFPSDrop: true });
       expect(hls.media).to.equal(null);
       const media = document.createElement('video');
@@ -62,7 +65,7 @@ describe('Hls', function () {
       hls.destroy();
     });
 
-    it('should add and remove refrences to the "media" element after attached', function () {
+    it('should add and remove references to the "media" element after attached', function () {
       const hls = new Hls({
         capLevelOnFPSDrop: true,
         emeEnabled: true,
@@ -77,14 +80,45 @@ describe('Hls', function () {
       detachTest(hls, media, 12);
       hls.destroy();
     });
+
+    it('should trigger an error event when attachMedia is called with null', function () {
+      const hls = new Hls();
+      const triggerSpy = sinon.spy(hls, 'trigger');
+
+      hls.on(Events.ERROR, function (_event, _data) {});
+      (hls as any).attachMedia(null);
+
+      const expectedEvent = {
+        type: ErrorTypes.OTHER_ERROR,
+        details: ErrorDetails.ATTACH_MEDIA_ERROR,
+        fatal: true,
+        error: sinon.match
+          .instanceOf(Error)
+          .and(
+            sinon.match.has(
+              'message',
+              'attachMedia failed: media argument is null',
+            ),
+          ),
+      };
+
+      expect(triggerSpy).to.be.calledWith(
+        Events.ERROR,
+        sinon.match(expectedEvent),
+      );
+
+      triggerSpy.restore();
+      hls.destroy();
+    });
   });
 
   describe('loadSource and url', function () {
-    it('url should initally be null', function () {
+    it('url should initially be null', function () {
       const hls = new Hls();
       expect(hls.url).to.equal(null);
       hls.destroy();
     });
+
     it('should return given url after load', function () {
       const hls = new Hls();
       hls.loadSource(
@@ -95,6 +129,7 @@ describe('Hls', function () {
       );
       hls.destroy();
     });
+
     it('should make relative url absolute', function () {
       const hls = new Hls();
       hls.loadSource('/streams/x36xhzz/x36xhzz.m3u8');