Komponententests in Office-Add-Ins

Komponententests überprüfen die Funktionalität Ihres Add-Ins, ohne dass Netzwerk- oder Dienstverbindungen erforderlich sind, einschließlich Verbindungen mit der Office-Anwendung. Serverseitiger Code für Komponententests und clientseitiger Code, der dieOffice-JavaScript-APIs nicht aufruft, sind in Office-Add-Ins identisch mit allen Webanwendungen, sodass keine spezielle Dokumentation erforderlich ist. Clientseitiger Code, der die Office-JavaScript-APIs aufruft, ist jedoch schwierig zu testen. Um diese Probleme zu lösen, haben wir eine Bibliothek erstellt, um die Erstellung von Simulierten Office-Objekten in Komponententests zu vereinfachen: Office-Addin-Mock. Die Bibliothek erleichtert das Testen auf folgende Weise:

• Die Office JavaScript-APIs müssen in einem Webview-Steuerelement im Kontext einer Office-Anwendung (z. B. Excel, PowerPoint oder Word) initialisiert werden, damit sie nicht in dem Prozess geladen werden können, in dem Komponententests auf Ihrem Entwicklungscomputer ausgeführt werden. Sie können die Office-Addin-Mock-Bibliothek in Ihre Testdateien importieren, was das Simulieren von Office-JavaScript-APIs innerhalb des Node.js Prozesses ermöglicht, in dem die Tests ausgeführt werden.
• Die anwendungsspezifischen APIs verfügen über Lade- und Synchronisierungsmethoden , die Sie relativ zu anderen Funktionen und zueinander in einer bestimmten Reihenfolge aufrufen müssen. Darüber hinaus müssen Sie die load -Methode mit bestimmten Parametern aufrufen, abhängig von den Eigenschaften von Office-Objekten, die später in der zu testierenden Funktion vom Code gelesen werden. Komponententestframeworks sind jedoch inhärent zustandslos, sodass sie nicht aufzeichnen können, ob load oder sync aufgerufen wurde oder welche Parameter an loadübergeben wurden. Die Modellobjekte, die Sie mit der Office-Addin-Mock-Bibliothek erstellen, verfügen über einen internen Zustand, der diese Elemente nachverfolgt. Dieser interne Zustand ermöglicht es den Pseudoobjekten, das Fehlerverhalten tatsächlicher Office-Objekte zu emulieren. Wenn z. B. die getestete Funktion versucht, eine Eigenschaft zu lesen, die nicht zuerst an loadübergeben wurde, gibt der Test einen Fehler zurück, der dem ähnelt, was Office zurückgeben würde.

Die Bibliothek ist nicht von den Office JavaScript-APIs abhängig, und Sie können sie mit jedem JavaScript-Komponententestframework verwenden, z. B.:

• Scherzen
• Mokka
• Jasmin

In den Beispielen in diesem Artikel wird das Jest-Framework verwendet. Beispiele, die das Mocha-Framework verwenden, finden Sie auf der Office-Addin-Mock-Homepage.

Voraussetzungen

In diesem Artikel wird davon ausgegangen, dass Sie mit den grundlegenden Konzepten von Komponententests und -mocking vertraut sind, einschließlich der Erstellung und Ausführung von Testdateien, und dass Sie über einige Erfahrung mit einem Komponententestframework verfügen.

Installieren des Tools

Öffnen Sie zum Installieren der Bibliothek eine Eingabeaufforderung, navigieren Sie zum Stammverzeichnis Ihres Add-In-Projekts, und geben Sie den folgenden Befehl ein.

npm install office-addin-mock --save-dev

Grundlegende Nutzung

1. Ihr Projekt verfügt über eine oder mehrere Testdateien. (Die Anweisungen für Ihr Testframework und die Beispieltestdateien finden Sie unten in den Beispielen.) Importieren Sie die Bibliothek mit dem oder Schlüsselwort (keyword) requireimport in eine beliebige Testdatei, die einen Test einer Funktion enthält, die die Office JavaScript-APIs aufruft, wie in den folgenden Beispielen gezeigt.

   // CommonJS
   const OfficeAddinMock = require("office-addin-mock");
   

   // ES6
   import OfficeAddinMock from "office-addin-mock";
   

2. Importieren Sie das Modul, das die Add-In-Funktion enthält, die Sie mit oder requireimport Schlüsselwort (keyword) testen möchten. In den folgenden Beispielen wird davon ausgegangen, dass sich Ihre Testdatei in einem Unterordner des Ordners mit den Codedateien Ihres Add-Ins befindet.

   // CommonJS
   const myOfficeAddinFeature = require("../my-office-add-in");
   

   // ES6
   import myOfficeAddinFeature from "../my-office-add-in";
   

3. Erstellen Sie ein Datenobjekt mit den Eigenschaften und Untereigenschaften, die Sie zum Testen der Funktion simulieren müssen. Das folgende Beispiel zeigt ein Objekt, das die Excel Workbook.range.address-Eigenschaft und die Workbook.getSelectedRange-Methode simuliert. Dieses Objekt ist nicht das letzte Pseudoobjekt. Stellen Sie sich dies als Seedobjekt vor, das verwendet, OfficeMockObject um das endgültige Pseudoobjekt zu erstellen.

   const mockData = {
     workbook: {
       range: {
         address: "C2:G3",
       },
       getSelectedRange: function () {
         return this.range;
       },
     },
   };
   

4. Übergeben Sie das Datenobjekt an den OfficeMockObject Konstruktor. Beachten Sie Folgendes zum zurückgegebenen OfficeMockObject Objekt.

   • Es handelt sich um ein vereinfachtes Modell eines OfficeExtension.ClientRequestContext-Objekts .
   • Das Mockobjekt verfügt über alle Member des Datenobjekts und verfügt auch über Pseudoimplementierungen der load Methoden und sync .
   • Das Pseudoobjekt imitiert das entscheidende Fehlerverhalten des ClientRequestContext Objekts. Wenn beispielsweise die Office-API, die Sie testen, versucht, eine Eigenschaft zu lesen, ohne zuerst die Eigenschaft zu laden und aufzurufen sync, schlägt der Test mit einem Fehler fehl, der dem ähnelt, was in der Produktionslaufzeit ausgelöst wird: "Fehler, Eigenschaft nicht geladen".

   const contextMock = new OfficeAddinMock.OfficeMockObject(mockData);
   

   Hinweis

   Die vollständige Referenzdokumentation für den OfficeMockObject Typ finden Sie unter Office-Addin-Mock.

5. Fügen Sie in der Syntax Ihres Testframeworks einen Test der Funktion hinzu. Verwenden Sie das OfficeMockObject -Objekt anstelle des Objekts, das es simuliert, in diesem Fall das ClientRequestContext -Objekt. Im Folgenden wird das Beispiel in Jest fortgesetzt. Bei diesem Beispieltest wird davon ausgegangen, dass die getestete Add-In-Funktion den Namen trägt getSelectedRangeAddress, dass sie ein ClientRequestContext -Objekt als Parameter akzeptiert und die Adresse des aktuell ausgewählten Bereichs zurückgibt. Das vollständige Beispiel finden Sie weiter unten in diesem Artikel.

   test("getSelectedRangeAddress should return the address of the range", async function () {
     expect(await getSelectedRangeAddress(contextMock)).toBe("C2:G3");
   });
   

6. Führen Sie den Test gemäß der Dokumentation des Testframeworks und Ihrer Entwicklungstools aus. In der Regel gibt es eine package.json-Datei mit einem Skript, das das Testframework ausführt. Wenn z. B. Jest das Framework ist, enthält package.json Folgendes:

   "scripts": {
     "test": "jest",
     -- Other scripts omitted. --  
   }
   

   Um den Test auszuführen, geben Sie Folgendes in einer Eingabeaufforderung im Stammverzeichnis des Projekts ein.

   npm test
   

Beispiele

In den Beispielen in diesem Abschnitt wird Jest mit den Standardeinstellungen verwendet. Diese Einstellungen unterstützen CommonJS-Module. Informationen zum Konfigurieren von Jest und Node.js für die Verwendung von TypeScript und zur Unterstützung von ECMAScript-Modulen finden Sie in der Jest-Dokumentation zu den ersten Schritten und ECMAScript-Modulen.

Führen Sie die folgenden Schritte aus, um eines dieser Beispiele auszuführen.

1. Erstellen Sie ein Office-Add-In-Projekt für die entsprechende Office-Hostanwendung (z. B. Excel oder Word). Eine Möglichkeit, dies schnell zu tun, ist die Verwendung des Yeoman-Generators für Office-Add-Ins.
2. Installieren Sie im Stammverzeichnis des Projekts Jest.
3. Installieren Sie das Tool office-addin-mock.
4. Erstellen Sie eine Datei genau wie die erste Datei im Beispiel, und fügen Sie sie dem Ordner hinzu, der die anderen Quelldateien des Projekts enthält, die häufig als bezeichnet werden \src.
5. Erstellen Sie einen Unterordner für den Quelldateiordner, und geben Sie ihm einen entsprechenden Namen, z \tests. B. .
6. Erstellen Sie eine Datei genau wie die Testdatei im Beispiel, und fügen Sie sie dem Unterordner hinzu.
7. Fügen Sie der package.json-Datei ein test Skript hinzu, und führen Sie dann den Test aus, wie unter Grundlegende Verwendung beschrieben.

Simulieren der allgemeinen Office-APIs

In diesem Beispiel wird davon ausgegangen, dass office-Add-Ins für jeden Host verwendet werden, der die allgemeinen Office-APIs unterstützt (z. B. Excel, PowerPoint oder Word). Das Add-In verfügt über eines seiner Features in einer Datei namens my-common-api-add-in-feature.js. Der folgende Code zeigt den Inhalt der Datei. Die addHelloWorldText Funktion legt den Text "Hallo Welt!" auf den aktuell im Dokument ausgewählten Text fest, z. B. einen Bereich in Word, eine Zelle in Excel oder ein Textfeld in PowerPoint.

const myCommonAPIAddinFeature = {

    addHelloWorldText: async () => {
        const options = { coercionType: Office.CoercionType.Text };
        await Office.context.document.setSelectedDataAsync("Hello World!", options);
    }
}
  
module.exports = myCommonAPIAddinFeature;

Die Testdatei mit dem Namen my-common-api-add-in-feature.test.jsbefindet sich relativ zum Speicherort der Add-In-Codedatei in einem Unterordner. Der folgende Code zeigt den Inhalt der Datei. Die Eigenschaft der obersten Ebene ist context, ein Office.Context-Objekt , sodass das Objekt, das simuliert wird, das übergeordnete Objekt dieser Eigenschaft ist: ein Office-Objekt . Zu diesem Code ist Folgendes anzumerken:

• Der OfficeMockObject Konstruktor fügt dem Pseudoobjekt Office nicht alle Office-Enumerationsklassen hinzu. Daher müssen Sie den CoercionType.Text Wert hinzufügen, auf den in der Add-In-Methode explizit im Seedobjekt verwiesen wird.
• Da die Office JavaScript-Bibliothek nicht im Knotenprozess geladen wird, müssen Sie das Office Objekt deklarieren und initialisieren, auf das im Add-In-Code verwiesen wird.

const OfficeAddinMock = require("office-addin-mock");
const myCommonAPIAddinFeature = require("../my-common-api-add-in-feature");

// Create the seed mock object.
const mockData = {
    context: {
      document: {
        setSelectedDataAsync: function (data, options) {
          this.data = data;
          this.options = options;
        },
      },
    },
    // Mock the Office.CoercionType enum.
    CoercionType: {
      Text: {},
    },
};
  
// Create the final mock object from the seed object.
const officeMock = new OfficeAddinMock.OfficeMockObject(mockData);

// Create the Office object that is called in the addHelloWorldText function.
global.Office = officeMock;

/* Code that calls the test framework goes below this line. */

// Jest test
test("Text of selection in document should be set to 'Hello World'", async function () {
    await myCommonAPIAddinFeature.addHelloWorldText();
    expect(officeMock.context.document.data).toBe("Hello World!");
});

Simulieren der Outlook-APIs

Obwohl die Outlook-APIs Teil des allgemeinen API-Modells sind, verfügen sie über eine spezielle Architektur, die auf dem Mailbox-Objekt basiert. Wir bieten ein eindeutiges Beispiel für Outlook. In diesem Beispiel wird davon ausgegangen, dass ein Outlook-Add-In über eines seiner Features in einer Datei namens verfügt my-outlook-add-in-feature.js. Der folgende Code zeigt den Inhalt der Datei. Die addHelloWorldText Funktion legt den Text "Hallo Welt!" auf den wert fest, der derzeit im Fenster zum Verfassen von Nachrichten ausgewählt ist.

const myOutlookAddinFeature = {

    addHelloWorldText: async () => {
        Office.context.mailbox.item.setSelectedDataAsync("Hello World!");
      }
}

module.exports = myOutlookAddinFeature;

Die Testdatei mit dem Namen my-outlook-add-in-feature.test.jsbefindet sich relativ zum Speicherort der Add-In-Codedatei in einem Unterordner. Der folgende Code zeigt den Inhalt der Datei. Die Eigenschaft der obersten Ebene ist context, ein Office.Context-Objekt . Das Objekt, auf das das Modell abzielt, ist das übergeordnete Objekt dieser Eigenschaft: ein Office-Objekt . Beachten Sie die folgenden Details zu diesem Code.

• Die host -Eigenschaft des Pseudoobjekts wird intern von der Modellbibliothek verwendet, um die Office-Anwendung zu identifizieren. Dies ist für Outlook obligatorisch. Es dient derzeit keinem Zweck für andere Office-Anwendungen.
• Da die Office JavaScript-Bibliothek nicht im Knotenprozess geladen wird, müssen Sie das Office Objekt deklarieren und initialisieren, auf das im Add-In-Code verwiesen wird.

const OfficeAddinMock = require("office-addin-mock");
const myOutlookAddinFeature = require("../my-outlook-add-in-feature");

// Create the seed mock object.
const mockData = {
  // Identify the host to the mock library (required for Outlook).
  host: "outlook",
  context: {
    mailbox: {
      item: {
          setSelectedDataAsync: function (data) {
          this.data = data;
        },
      },
    },
  },
};
  
// Create the final mock object from the seed object.
const officeMock = new OfficeAddinMock.OfficeMockObject(mockData);

// Create the Office object that is called in the addHelloWorldText function.
global.Office = officeMock;

/* Code that calls the test framework goes below this line. */

// Jest test
test("Text of selection in message should be set to 'Hello World'", async function () {
    await myOutlookAddinFeature.addHelloWorldText();
    expect(officeMock.context.mailbox.item.data).toBe("Hello World!");
});

Simulieren der anwendungsspezifischen Office-APIs

Wenn Sie Funktionen testen, die die anwendungsspezifischen APIs verwenden, simulieren Sie den richtigen Objekttyp. Sie haben zwei Möglichkeiten.

• Simulieren sie ein OfficeExtension.ClientRequestObject. Verwenden Sie diese Option, wenn die getestete Funktion die beiden folgenden Bedingungen erfüllt.

  • Es ruft keinen Host auf. run -Funktion, z. B. Excel.run.
  • Es verweist nicht auf eine andere direkte Eigenschaft oder Methode eines Host-Objekts .

• Simulieren sie ein Host-Objekt, z. B. Excel oder Word. Verwenden Sie diese Option, wenn die vorherige Option nicht möglich ist.

Die folgenden Unterabschnitte zeigen Beispiele für beide Arten von Tests.

Simulieren eines ClientRequestContext-Objekts

In diesem Beispiel wird davon ausgegangen, dass ein Excel-Add-In über eines seiner Features in einer Datei namens verfügt my-excel-add-in-feature.js. Der folgende Code zeigt den Inhalt der Datei. Beachten Sie, dass es sich bei der getSelectedRangeAddress Funktion um eine Hilfsmethode namens innerhalb des Rückrufs handelt, der an Excel.runübergeben wird.

const myExcelAddinFeature = {
    
    getSelectedRangeAddress: async (context) => {
        const range = context.workbook.getSelectedRange();      
        range.load("address");

        await context.sync();
      
        return range.address;
    }
}

module.exports = myExcelAddinFeature;

Die Testdatei mit dem Namen my-excel-add-in-feature.test.jsbefindet sich relativ zum Speicherort der Add-In-Codedatei in einem Unterordner. Der folgende Code zeigt den Inhalt der Datei. Beachten Sie, dass die Eigenschaft der obersten Ebene ist workbook, sodass das Objekt, das simuliert wird, das übergeordnete Objekt eines Excel.Workbookist: ein ClientRequestContext -Objekt.

const OfficeAddinMock = require("office-addin-mock");
const myExcelAddinFeature = require("../my-excel-add-in-feature");

// Create the seed mock object.
const mockData = {
    workbook: {
      range: {
        address: "C2:G3",
      },
      // Mock the Workbook.getSelectedRange method.
      getSelectedRange: function () {
        return this.range;
      },
    },
};

// Create the final mock object from the seed object.
const contextMock = new OfficeAddinMock.OfficeMockObject(mockData);

/* Code that calls the test framework goes below this line. */

// Jest test
test("getSelectedRangeAddress should return address of selected range", async function () {
  expect(await myOfficeAddinFeature.getSelectedRangeAddress(contextMock)).toBe("C2:G3");
});

Simulieren eines Hostobjekts

In diesem Beispiel wird davon ausgegangen, dass ein Word-Add-In über eines seiner Features in einer Datei namens verfügtmy-word-add-in-feature.js. Der folgende Code zeigt den Inhalt der Datei.

const myWordAddinFeature = {

  insertBlueParagraph: async () => {
    return Word.run(async (context) => {
      // Insert a paragraph at the end of the document.
      const paragraph = context.document.body.insertParagraph("Hello World", Word.InsertLocation.end);
  
      // Change the font color to blue.
      paragraph.font.color = "blue";
  
      await context.sync();
    });
  }
}

module.exports = myWordAddinFeature;

Die Testdatei mit dem Namen my-word-add-in-feature.test.jsbefindet sich relativ zum Speicherort der Add-In-Codedatei in einem Unterordner. Der folgende Code zeigt den Inhalt der Datei. Beachten Sie, dass die Eigenschaft der obersten Ebene ein ClientRequestContext -Objekt istcontext, sodass das Objekt, das simuliert wird, das übergeordnete Objekt dieser Eigenschaft ist: ein Word -Objekt. Beachten Sie die folgenden Details zu diesem Code.

• Wenn der OfficeMockObject Konstruktor das endgültige Pseudoobjekt erstellt, stellt er sicher, dass das untergeordnete ClientRequestContext Objekt über - und load -Methoden verfügtsync.
• Der OfficeMockObject Konstruktor fügt run dem Pseudoobjekt Word keine Funktion hinzu, daher müssen Sie sie explizit im Seedobjekt hinzufügen.
• Der OfficeMockObject Konstruktor fügt dem Pseudoobjekt Word nicht alle Word Enumerationsklassen hinzu. Daher müssen Sie den InsertLocation.end Wert hinzufügen, auf den in der Add-In-Methode explizit im Seedobjekt verwiesen wird.
• Da die Office JavaScript-Bibliothek nicht im Knotenprozess geladen wird, müssen Sie das Word Objekt deklarieren und initialisieren, auf das im Add-In-Code verwiesen wird.

const OfficeAddinMock = require("office-addin-mock");
const myWordAddinFeature = require("../my-word-add-in-feature");

// Create the seed mock object.
const mockData = {
  context: {
    document: {
      body: {
        paragraph: {
          font: {},
        },
        // Mock the Body.insertParagraph method.
        insertParagraph: function (paragraphText, insertLocation) {
          this.paragraph.text = paragraphText;
          this.paragraph.insertLocation = insertLocation;
          return this.paragraph;
        },
      },
    },
  },
  // Mock the Word.InsertLocation enum.
  InsertLocation: {
    end: "end",
  },
  // Mock the Word.run function.
  run: async function(callback) {
    await callback(this.context);
  },
};

// Create the final mock object from the seed object.
const wordMock = new OfficeAddinMock.OfficeMockObject(mockData);

// Define and initialize the Word object that is called in the insertBlueParagraph function.
global.Word = wordMock;

/* Code that calls the test framework goes below this line. */

// Jest test set
describe("Insert blue paragraph at end tests", () => {

  test("color of paragraph", async function () {
    await myWordAddinFeature.insertBlueParagraph();  
    expect(wordMock.context.document.body.paragraph.font.color).toBe("blue");
  });

  test("text of paragraph", async function () {
    await myWordAddinFeature.insertBlueParagraph();
    expect(wordMock.context.document.body.paragraph.text).toBe("Hello World");
  });
})

Siehe auch

• Installationspunkt der Npm-Seite von Office-Addin-Mock .
• Das Open Source Repository ist Office-Addin-Mock.
• Scherzen
• Mokka
• Jasmin