Teste de unidades nos Suplementos do Office

Os testes de unidades marcar a funcionalidade do suplemento sem necessidade de ligações de rede ou de serviço, incluindo ligações à aplicação do Office. O código do lado do servidor de teste de unidades e o código do lado do cliente que não chama as APIs JavaScript do Office são os mesmos nos Suplementos do Office que estão em qualquer aplicação Web, pelo que não requer documentação especial. No entanto, o código do lado do cliente que chama as APIs javaScript do Office é um desafio para testar. Para resolver estes problemas, criámos uma biblioteca para simplificar a criação de objetos fictícios do Office em testes de unidades: Office-Addin-Mock. A biblioteca facilita os testes das seguintes formas:

• As APIs javaScript do Office têm de ser inicializadas num controlo webview no contexto de uma aplicação do Office (como o Excel, PowerPoint ou Word), para que não possam carregar no processo em que os testes de unidades são executados no seu computador de desenvolvimento. Pode importar a biblioteca Office-Addin-Mock para os seus ficheiros de teste, o que permite a simulação das APIs JavaScript do Office dentro do processo de Node.js em que os testes são executados.
• As APIs específicas da aplicação têm métodos de carregamento e sincronização que tem de chamar numa ordem específica relativamente a outras funções e entre si. Além disso, tem de chamar o load método com determinados parâmetros consoante as propriedades dos objetos do Office que serão lidas pelo código mais tarde na função que está a ser testada. No entanto, as arquiteturas de teste de unidades são inerentemente sem estado, pelo que não podem manter um registo de se load foram ou sync foram chamadas ou que parâmetros foram transmitidos para load. Os objetos fictícios que cria com a biblioteca Office-Addin-Mock têm um estado interno que controla estes itens. Este estado interno permite que os objetos fictícios emulem o comportamento de erro dos objetos reais do Office. Por exemplo, se a função que está a ser testada tentar ler uma propriedade que não foi transmitida pela primeira vez a load, o teste devolve um erro semelhante ao que o Office devolveria.

A biblioteca não depende das APIs JavaScript do Office e pode utilizá-la com qualquer arquitetura de teste de unidades javaScript, como:

• Jest
• Mocha
• Jasmim

Os exemplos neste artigo utilizam a arquitetura Jest. Para obter exemplos que utilizam a arquitetura Mocha, consulte a home page do Office-Addin-Mock.

Pré-requisitos

Este artigo pressupõe que está familiarizado com os conceitos básicos de teste e simulação de unidades, incluindo como criar e executar ficheiros de teste e que tem alguma experiência com uma arquitetura de teste de unidades.

Instalar a ferramenta

Para instalar a biblioteca, abra uma linha de comandos, navegue para a raiz do projeto de suplemento e introduza o seguinte comando.

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

Utilização básica

1. O seu projeto terá um ou mais ficheiros de teste. (Veja as instruções para a arquitetura de teste e os ficheiros de teste de exemplo em Exemplos abaixo.) Importe a biblioteca com o require ou import palavra-chave para qualquer ficheiro de teste que tenha um teste de uma função que chame as APIs javaScript do Office, conforme mostrado nos exemplos seguintes.

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

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

2. Importe o módulo que contém a função de suplemento que pretende testar com o require ou import palavra-chave. Os exemplos seguintes partem do princípio de que o ficheiro de teste está numa subpasta da pasta com os ficheiros de código do suplemento.

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

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

3. Crie um objeto de dados que tenha as propriedades e subpropriedades que precisa de simular para testar a função. O exemplo seguinte mostra um objeto que ridiculariza a propriedade Livro.intervalo.endereço do Excel e o método Workbook.getSelectedRange . Este objeto não é o objeto simulado final. Pense nele como um objeto de semente que OfficeMockObject utiliza para criar o objeto de simulação final.

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

4. Transmita o objeto de dados para o OfficeMockObject construtor. Tenha em atenção o seguinte sobre o objeto devolvido OfficeMockObject .

   • É uma simulação simplificada de um objeto OfficeExtension.ClientRequestContext .
   • O objeto simulado tem todos os membros do objeto de dados e também tem implementações fictícias dos load métodos e sync .
   • O objeto de simulação imita o comportamento de erro crucial do ClientRequestContext objeto. Por exemplo, se a API do Office que está a testar tentar ler uma propriedade sem primeiro carregar a propriedade e chamar sync, o teste falhará com um erro semelhante ao que seria emitido no runtime de produção: "Erro, propriedade não carregada".

   const contextMock = new OfficeAddinMock.OfficeMockObject(mockData);
   

   Observação

   A documentação de referência completa para o OfficeMockObject tipo está em Office-Addin-Mock.

5. Na sintaxe da arquitetura de teste, adicione um teste à função. Utilize o OfficeMockObject objeto em vez do objeto que simula, neste caso, o ClientRequestContext objeto. Segue-se o exemplo em Jest. Este teste de exemplo pressupõe que a função de suplemento que está a ser testada é denominada getSelectedRangeAddress, que utiliza um ClientRequestContext objeto como parâmetro e que devolve o endereço do intervalo atualmente selecionado. O exemplo completo é apresentado mais adiante neste artigo.

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

6. Execute o teste de acordo com a documentação da arquitetura de teste e das suas ferramentas de desenvolvimento. Normalmente, existe um ficheiro package.json com um script que executa a arquitetura de teste. Por exemplo, se jest for a arquitetura, package.json conteria o seguinte:

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

   Para executar o teste, introduza o seguinte numa linha de comandos na raiz do projeto.

   npm test
   

Exemplos

Os exemplos nesta secção utilizam o Jest com as predefinições. Estas definições suportam módulos CommonJS. Para obter informações sobre como configurar o Jest e Node.js para utilizar o TypeScript e suportar módulos ECMAScript, veja a documentação Jest sobre como começar e Módulos ECMAScript.

Para executar qualquer um destes exemplos, siga os seguintes passos.

1. Crie um projeto de Suplemento do Office para a aplicação anfitriã do Office adequada (por exemplo, Excel ou Word). Uma forma de o fazer rapidamente é utilizar o gerador Yeoman para Suplementos do Office.
2. Na raiz do projeto, instale o Jest.
3. Instale a ferramenta office-addin-mock.
4. Crie um ficheiro exatamente como o primeiro ficheiro no exemplo e adicione-o à pasta que contém os outros ficheiros de origem do projeto, muitas vezes denominados \src.
5. Crie uma subpasta para a pasta de ficheiros de origem e atribua-lhe um nome adequado, como \tests.
6. Crie um ficheiro exatamente como o ficheiro de teste no exemplo e adicione-o à subpasta.
7. Adicione um test script ao ficheiro package.json e, em seguida, execute o teste, conforme descrito em Utilização básica.

Simular as APIs Comuns do Office

Este exemplo pressupõe um Suplemento do Office para qualquer anfitrião que suporte as APIs Comuns do Office (por exemplo, Excel, PowerPoint ou Word). O suplemento tem uma das suas funcionalidades num ficheiro com o nome my-common-api-add-in-feature.js. O código seguinte mostra o conteúdo do ficheiro. A addHelloWorldText função define o texto "Olá, Mundo!" para o que estiver atualmente selecionado no documento; por exemplo, um intervalo no Word, uma célula no Excel ou uma caixa de texto no PowerPoint.

const myCommonAPIAddinFeature = {

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

O ficheiro de teste, denominado my-common-api-add-in-feature.test.js, está numa subpasta, relativa à localização do ficheiro de código do suplemento. O código seguinte mostra o conteúdo do ficheiro. A propriedade de nível superior é context, um objeto Office.Context , pelo que o objeto que está a ser ridicularizado é o elemento principal desta propriedade: um objeto do Office . Observe o seguinte sobre este código:

• O OfficeMockObject construtor não adiciona todas as classes de enumeração do Office ao objeto simulado Office , pelo que tem de adicionar o CoercionType.Text valor referenciado no método de suplemento explicitamente no objeto de seed.
• Uma vez que a biblioteca JavaScript do Office não é carregada no processo do nó, tem de declarar e inicializar o Office objeto que é referenciado no código do suplemento.

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!");
});

Simular as APIs do Outlook

Embora as APIs do Outlook façam parte do modelo de API Comum, têm uma arquitetura especial criada em torno do objeto Caixa de Correio . Fornecemos um exemplo distinto para o Outlook. Este exemplo pressupõe um suplemento do Outlook que tem uma das respetivas funcionalidades num ficheiro com o nome my-outlook-add-in-feature.js. O código seguinte mostra o conteúdo do ficheiro. A addHelloWorldText função define o texto "Olá, Mundo!" para o que estiver atualmente selecionado na janela de composição de mensagens.

const myOutlookAddinFeature = {

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

module.exports = myOutlookAddinFeature;

O ficheiro de teste, denominado my-outlook-add-in-feature.test.js, está numa subpasta relativa à localização do ficheiro de código do suplemento. O código seguinte mostra o conteúdo do ficheiro. A propriedade de nível superior é context, um objeto Office.Context . O objeto que a simulação visa é o principal desta propriedade: um objeto do Office . Tenha em atenção os seguintes detalhes sobre este código.

• A host propriedade no objeto simulado é utilizada internamente pela biblioteca fictícia para identificar a aplicação do Office. É obrigatório para o Outlook. Atualmente, não serve para qualquer outra aplicação do Office.
• Uma vez que a biblioteca JavaScript do Office não é carregada no processo do nó, tem de declarar e inicializar o Office objeto que é referenciado no código do suplemento.

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!");
});

Simular as APIs específicas da aplicação do Office

Quando testa funções que utilizam as APIs específicas da aplicação, ridicularize o tipo certo de objeto. Tem duas opções.

• Simular um OfficeExtension.ClientRequestObject. Utilize esta opção quando a função que está a testar cumprir ambas as seguintes condições.

  • Não chama anfitrião. run função, como Excel.run.
  • Não referencia qualquer outra propriedade direta ou método de um objeto Anfitrião .

• Simular um objeto anfitrião, como o Excel ou Word. Utilize esta opção quando a opção anterior não for possível.

As subsecções seguintes mostram exemplos de ambos os tipos de testes.

Simular um objeto ClientRequestContext

Este exemplo pressupõe um suplemento do Excel que tem uma das respetivas funcionalidades num ficheiro com o nome my-excel-add-in-feature.js. O código seguinte mostra o conteúdo do ficheiro. Tenha em atenção que a getSelectedRangeAddress função é um método auxiliar chamado dentro da chamada de retorno que é transmitida para Excel.run.

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

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

module.exports = myExcelAddinFeature;

O ficheiro de teste, denominado my-excel-add-in-feature.test.js, está numa subpasta relativa à localização do ficheiro de código do suplemento. O código seguinte mostra o conteúdo do ficheiro. Tenha em atenção que a propriedade de nível superior é workbook, pelo que o objeto que está a ser simulado é o elemento principal de um Excel.Workbookobjeto : um ClientRequestContext .

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");
});

Simular um objeto anfitrião

Este exemplo pressupõe um suplemento Word que tem uma das suas funcionalidades num ficheiro com o nome my-word-add-in-feature.js. O código seguinte mostra o conteúdo do ficheiro.

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;

O ficheiro de teste, denominado my-word-add-in-feature.test.js, está numa subpasta relativa à localização do ficheiro de código do suplemento. O código seguinte mostra o conteúdo do ficheiro. Tenha em atenção que a propriedade de nível superior é context, um ClientRequestContext objeto, pelo que o objeto que está a ser simulado é o elemento principal desta propriedade: um Word objeto. Tenha em atenção os seguintes detalhes sobre este código.

• Quando o OfficeMockObject construtor cria o objeto simulado final, garante que o objeto subordinado ClientRequestContext tem sync e load métodos.
• O OfficeMockObject construtor não adiciona uma run função ao objeto simulado Word , pelo que tem de adicioná-la explicitamente ao objeto de semente.
• O OfficeMockObject construtor não adiciona todas as classes de enumeração Word ao objeto simuladoWord, pelo que tem de adicionar explicitamente o InsertLocation.end valor referenciado no método de suplemento no objeto de semente.
• Uma vez que a biblioteca JavaScript do Office não é carregada no processo do nó, tem de declarar e inicializar o Word objeto referenciado no código do suplemento.

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");
  });
})

Confira também

• Ponto de instalação da página npm Office-Addin-Mock .
• O repositório código aberto é Office-Addin-Mock.
• Jest
• Mocha
• Jasmim