Compartilhar via

Utilitários de teste dos visuais do Power BI

Este artigo ajudará você a instalar, importar e usar os utilitários de teste dos visuais do Power BI. Esses utilitários de teste podem ser usados para testes de unidade e incluem simulações e métodos para elementos como exibições de dados, seleções e esquemas de cores.

Pré-requisitos

Para usar este pacote, instale:

Instalação

Para instalar os utilitários de teste e adicionar as respectivas dependências ao package.json, execute o seguinte comando no diretório de visuais do Power BI:

npm install powerbi-visuals-utils-testutils --save

O exemplo a seguir fornece descrições e exemplos na API pública de utilitários de teste.

VisualBuilderBase

Usado pelo VisualBuilder em testes de unidade com os métodos usados com mais frequência build, update e updateRenderTimeout.

O método build retorna uma instância criada do visual.

Os métodos enumerateObjectInstances e updateEnumerateObjectInstancesRenderTimeout são necessários para verificar as alterações nas opções de bucket e de formatação.

abstract class VisualBuilderBase<T extends IVisual> {
    element: JQuery;
    viewport: IViewport;
    visualHost: IVisualHost;
    protected visual: T;
    constructor(width?: number, height?: number, guid?: string, element?: JQuery);
    protected abstract build(options: VisualConstructorOptions): T;
     nit(): void;
    destroy(): void;
    update(dataView: DataView[] | DataView): void;
    updateRenderTimeout(dataViews: DataView[] | DataView, fn: Function, timeout?: number): number;
    updateEnumerateObjectInstancesRenderTimeout(dataViews: DataView[] | DataView, options: EnumerateVisualObjectInstancesOptions, fn: (enumeration: VisualObjectInstance[]) => void, timeout?: number): number;
    updateFlushAllD3Transitions(dataViews: DataView[] | DataView): void;
    updateflushAllD3TransitionsRenderTimeout(dataViews: DataView[] | DataView, fn: Function, timeout?: number): number;
    enumerateObjectInstances(options: EnumerateVisualObjectInstancesOptions): VisualObjectInstance[];
}

Observação

Para obter mais exemplos, confira Como escrever testes de unidade para o VisualBuilderBase e um Cenário de uso real do VisualBuilderBase.

DataViewBuilder

Usado por TestDataViewBuilder, esse módulo fornece uma classe CategoricalDataViewBuilder usada no método createCategoricalDataViewBuilder. Também especifica as interfaces e os métodos necessários para trabalhar com um DataView fictício em testes de unidade.

  • O withValues adiciona colunas de série estática e o withGroupedValues adiciona colunas de série dinâmica.

    Não aplique a série dinâmica e a série estática a DataViewCategorical de um visual. Você só pode usá-las na consulta DataViewCategorical, em que DataViewTransform deverá dividi-las em objetos DataViewCategorical separados do visual.

  • O build retorna o DataView com metadados e o DataViewCategorical.

    build retorna Undefined se a combinação de parâmetros é inválida, como a inclusão de séries dinâmicas e estáticas ao criar a DataView do visual.

class CategoricalDataViewBuilder implements IDataViewBuilderCategorical {
    withCategory(options: DataViewBuilderCategoryColumnOptions): IDataViewBuilderCategorical;
    withCategories(categories: DataViewCategoryColumn[]): IDataViewBuilderCategorical;
    withValues(options: DataViewBuilderValuesOptions): IDataViewBuilderCategorical;
    withGroupedValues(options: DataViewBuilderGroupedValuesOptions): IDataViewBuilderCategorical;
    build(): DataView;
}

function createCategoricalDataViewBuilder(): IDataViewBuilderCategorical;

TestDataViewBuilder

Usado para a criação de VisualData em testes de unidade. Quando os dados são colocados em buckets de campo de dados, o Power BI Produz um objeto DataView categórico com base nos dados. O TestDataViewBuilder ajuda a simular a criação de uma DataView categórica.

abstract class TestDataViewBuilder {
    static DataViewName: string;
    private aggregateFunction;
    static setDefaultQueryName(source: DataViewMetadataColumn): DataViewMetadataColumn;
    static getDataViewBuilderColumnIdentitySources(options: TestDataViewBuilderColumnOptions[] | TestDataViewBuilderColumnOptions): DataViewBuilderColumnIdentitySource[];
    static getValuesTable(categories?: DataViewCategoryColumn[], values?: DataViewValueColumn[]): any[][];
    static createDataViewBuilderColumnOptions(categoriesColumns: (TestDataViewBuilderCategoryColumnOptions | TestDataViewBuilderCategoryColumnOptions[])[], valuesColumns: (DataViewBuilderValuesColumnOptions | DataViewBuilderValuesColumnOptions[])[], filter?: (options: TestDataViewBuilderColumnOptions) => boolean, customizeColumns?: CustomizeColumnFn): DataViewBuilderAllColumnOptions;
    static setUpDataViewBuilderColumnOptions(options: DataViewBuilderAllColumnOptions, aggregateFunction: (array: number[]) => number): DataViewBuilderAllColumnOptions;
    static setUpDataView(dataView: DataView, options: DataViewBuilderAllColumnOptions): DataView;
    protected createCategoricalDataViewBuilder(categoriesColumns: (TestDataViewBuilderCategoryColumnOptions | TestDataViewBuilderCategoryColumnOptions[])[], valuesColumns: (DataViewBuilderValuesColumnOptions | DataViewBuilderValuesColumnOptions[])[], columnNames: string[], customizeColumns?: CustomizeColumnFn): IDataViewBuilderCategorical;
    abstract getDataView(columnNames?: string[]): DataView;
}

A seguinte lista apresenta as interfaces usadas com mais frequência ao criar uma testDataView:

interface TestDataViewBuilderColumnOptions extends DataViewBuilderColumnOptions {
    values: any[];
}

interface TestDataViewBuilderCategoryColumnOptions extends TestDataViewBuilderColumnOptions {
    objects?: DataViewObjects[];
    isGroup?: boolean;
}

interface DataViewBuilderColumnOptions {
    source: DataViewMetadataColumn;
}

interface DataViewBuilderSeriesData {
    values: PrimitiveValue[];
    highlights?: PrimitiveValue[];
    /** Client-computed maximum value for a column. */
    maxLocal?: any;
    /** Client-computed maximum value for a column. */
    minLocal?: any;
}

interface DataViewBuilderColumnIdentitySource {
    fields: any[];
    identities?: CustomVisualOpaqueIdentity[];
}

Observação

Para obter mais exemplos, confira Como escrever testes de unidade TestDataViewBuilder e Cenário de uso real do TestDataViewBuilder.

Simulações

MockIVisualHost

Implementa IVisualHost para testar os visuais do Power BI sem dependências externas, como a estrutura do Power BI.

Os métodos úteis incluem createSelectionIdBuilder, createSelectionManager, createLocalizationManager e as propriedades getter.

import powerbi from "powerbi-visuals-api";

import VisualObjectInstancesToPersist = powerbi.VisualObjectInstancesToPersist;
import ISelectionIdBuilder = powerbi.visuals.ISelectionIdBuilder;
import ISelectionManager = powerbi.extensibility.ISelectionManager;
import IColorPalette = powerbi.extensibility.IColorPalette;
import IVisualEventService = powerbi.extensibility.IVisualEventService;
import ITooltipService = powerbi.extensibility.ITooltipService;
import IVisualHost = powerbi.extensibility.visual.IVisualHost;

class MockIVisualHost implements IVisualHost {
      constructor(
          colorPalette?: IColorPalette,
          selectionManager?: ISelectionManager,
          tooltipServiceInstance?: ITooltipService,
          localeInstance?: MockILocale,
          allowInteractionsInstance?: MockIAllowInteractions,
          localizationManager?: powerbi.extensibility.ILocalizationManager,
          telemetryService?: powerbi.extensibility.ITelemetryService,
          authService?: powerbi.extensibility.IAuthenticationService,
          storageService?: ILocalVisualStorageService,
          eventService?: IVisualEventService);
      createSelectionIdBuilder(): ISelectionIdBuilder;
      createSelectionManager(): ISelectionManager;
      createLocalizationManager(): ILocalizationManager;
      colorPalette: IColorPalette;
      locale: string;
      telemetry: ITelemetryService;
      tooltipService: ITooltipService;
      allowInteractios: boolean;
      storageService: ILocalVisualStorageService;
      eventService: IVisualEventService;
      persistProperties(changes: VisualObjectInstancesToPersist): void;
}

  • O createVisualHost cria e retorna uma instância do IVisualHost, na verdade, MockIVisualHost.

    function createVisualHost(locale?: Object, allowInteractions?: boolean, colors?: IColorInfo[], isEnabled?: boolean, displayNames?: any, token?: string): IVisualHost;

    Exemplo:

    import { createVisualHost } from "powerbi-visuals-utils-testutils"

let host: IVisualHost = createVisualHost();

Importante

O MockIVisualHost é uma implementação fictícia de IVisualHost e só deve ser usado com testes de unidade.

MockIColorPalette

Implementa IColorPalette para testar os visuais do Power BI sem dependências externas, como a estrutura do Power BI.

O MockIColorPalette fornece propriedades úteis para verificar o esquema de cores ou o modo de alto contraste em testes de unidade.

import powerbi from "powerbi-visuals-api";
import IColorPalette = powerbi.extensibility.ISandboxExtendedColorPalette;
import IColorInfo = powerbi.IColorInfo;

class MockIColorPalette implements IColorPalette {
    constructor(colors?: IColorInfo[]);
    getColor(key: string): IColorInfo;
    reset(): IColorPalette;
    isHighContrastMode: boolean;
    foreground: {value: string};
    foregroundLight: {value: string};
    ...
    background: {value: string};
    backgroundLight: {value: string};
    ...
    shapeStroke: {value: string};
}

  • O createColorPalette cria e retorna uma instância de IColorPalette, na verdade, MockIColorPalette.

    function createColorPalette(colors?: IColorInfo[]): IColorPalette;

    Exemplo:

    import { createColorPalette } from "powerbi-visuals-utils-testutils"

let colorPalette: IColorPalette = createColorPalette();

Importante

O MockIColorPalette é uma implementação fictícia do IColorPalette e só deve ser usada com testes de unidade.

MockISelectionId

Implementa o ISelectionId para testar os visuais do Power BI sem dependências externas, como a estrutura do Power BI.

import powerbi from "powerbi-visuals-api";
import Selector = powerbi.data.Selector;
import ISelectionId = powerbi.visuals.ISelectionId;

class MockISelectionId implements ISelectionId {
    constructor(key: string);
    equals(other: ISelectionId): boolean;
    includes(other: ISelectionId, ignoreHighlight?: boolean): boolean;
    getKey(): string;
    getSelector(): Selector;
    getSelectorsByColumn(): Selector;
    hasIdentity(): boolean;
}

  • O createSelectionId cria e retorna uma instância do ISelectionId, na verdade, MockISelectionId.

    function createSelectionId(key?: string): ISelectionId;

    Exemplo:

    import { createColorPalette } from "powerbi-visuals-utils-testutils"

let selectionId: ISelectionId = createSelectionId();

Observação

O MockISelectionId é uma implementação fictícia do ISelectionId e só deve ser usado com testes de unidade.

MockISelectionIdBuilder

Implementa ISelectionIdBuilder para testar os visuais do Power BI sem dependências externas, como a estrutura do Power BI.

import DataViewCategoryColumn = powerbi.DataViewCategoryColumn;
import DataViewValueColumn = powerbi.DataViewValueColumn;
import DataViewValueColumnGroup = powerbi.DataViewValueColumnGroup;
import DataViewValueColumns = powerbi.DataViewValueColumns;
import ISelectionIdBuilder = powerbi.visuals.ISelectionIdBuilder;
import ISelectionId = powerbi.visuals.ISelectionId;

class MockISelectionIdBuilder implements ISelectionIdBuilder {
    withCategory(categoryColumn: DataViewCategoryColumn, index: number): this;
    withSeries(seriesColumn: DataViewValueColumns, valueColumn: DataViewValueColumn | DataViewValueColumnGroup): this;
    withMeasure(measureId: string): this;
    createSelectionId(): ISelectionId;
    withMatrixNode(matrixNode: DataViewMatrixNode, levels: DataViewHierarchyLevel[]): this;
    withTable(table: DataViewTable, rowIndex: number): this;
}

  • O createSelectionIdBuilder cria e retorna uma instância do ISelectionIdBuilder, na verdade, MockISelectionIdBuilder.

    function createSelectionIdBuilder(): ISelectionIdBuilder;

    Exemplo:

    import { selectionIdBuilder } from "powerbi-visuals-utils-testutils";

let selectionIdBuilder = createSelectionIdBuilder();

Observação

O MockISelectionIdBuilder é uma implementação fictícia do ISelectionIdBuilder e só deve ser usada com testes de unidade.

MockISelectionManager

Implementa ISelectionManager para testar os visuais do Power BI sem dependências externas, como a estrutura do Power BI.

import powerbi from "powerbi-visuals-api";
import IPromise = powerbi.IPromise;
import ISelectionId = powerbi.visuals.ISelectionId;
import ISelectionManager = powerbi.extensibility.ISelectionManager;

class MockISelectionManager implements ISelectionManager {
    select(selectionId: ISelectionId | ISelectionId[], multiSelect?: boolean): IPromise<ISelectionId[]>;
    hasSelection(): boolean;
    clear(): IPromise<{}>;
    getSelectionIds(): ISelectionId[];
    containsSelection(id: ISelectionId): boolean;
    showContextMenu(selectionId: ISelectionId, position: IPoint): IPromise<{}>;
    registerOnSelectCallback(callback: (ids: ISelectionId[]) => void): void;
    simutateSelection(selections: ISelectionId[]): void;
}

  • O createSelectionManager cria e retorna uma instância do ISelectionManager, na verdade, MockISelectionManager.

    function createSelectionManager(): ISelectionManager

    Exemplo:

    import { createSelectionManager } from "powerbi-visuals-utils-testutils";

let selectionManager: ISelectionManager = createSelectionManager();

Observação

O MockISelectionManager é uma implementação fictícia do ISelectionManager e só deve ser usado com testes de unidade.

MockILocale

Define a localidade e a altera de acordo com as suas necessidades durante o processo de teste de unidade.

class MockILocale {
    constructor(locales?: Object): void; // Default locales are en-US and ru-RU 
    locale(key: string): void;// setter property
    locale(): string; // getter property
}
  • O createLocale cria e retorna uma instância do MockILocale. 
    funciton createLocale(locales?: Object): MockILocale;

MockITooltipService

Simula o TooltipService e o chama de acordo com as suas necessidades durante o processo de teste de unidade.

class MockITooltipService implements ITooltipService {
    constructor(isEnabled: boolean = true);
    enabled(): boolean;
    show(options: TooltipShowOptions): void;
    move(options: TooltipMoveOptions): void;
    hide(options: TooltipHideOptions): void;
}
  • O createTooltipService cria e retorna uma instância do MockITooltipService. 
    function createTooltipService(isEnabled?: boolean): ITooltipService;

MockIAllowInteractions

export class MockIAllowInteractions {
    constructor(public isEnabled?: boolean); // false by default
}
  • O createAllowInteractions cria e retorna uma instância do MockIAllowInteractions. 
    function createAllowInteractions(isEnabled?: boolean): MockIAllowInteractions;

MockILocalizationManager

Fornece habilidades básicas do LocalizationManager, que são necessárias para o teste de unidade.

class MockILocalizationManager implements ILocalizationManager {
    constructor(displayNames: {[key: string]: string});
    getDisplayName(key: string): string; // returns default or setted displayNames for localized elements
}

  • O createLocalizationManager cria e retorna uma instância do ILocalizationManager, na verdade, MockILocalizationManager.

    function createLocalizationManager(displayNames?: any): ILocalizationManager;

    Exemplo:

    import { createLocalizationManager } from "powerbi-visuals-utils-testutils";
let localizationManagerMock: ILocalizationManager = createLocalizationManager();

MockITelemetryService

Simula o uso de TelemetryService.

class MockITelemetryService implements ITelemetryService {
    instanceId: string;
    trace(veType: powerbi.VisualEventType, payload?: string) {
    }
}

Criação de MockITelemetryServicetypescript function createTelemetryService(): ITelemetryService;

MockIAuthenticationService

Simula o trabalho de AuthenticationService fornecendo um token fictício do Microsoft Entra.

class MockIAuthenticationService implements IAuthenticationService  {
    constructor(token: string);
    getAADToken(visualId?: string): powerbi.IPromise<string>
}
  • O createAuthenticationService cria e retorna uma instância do IAuthenticationService, na verdade, MockIAuthenticationService. 
    function createAuthenticationService(token?: string): IAuthenticationService;

MockIStorageService

Permite o uso de ILocalVisualStorageService com o mesmo comportamento de LocalStorage.

class MockIStorageService implements ILocalVisualStorageService {
  get(key: string): IPromise<string>;
  set(key: string, data: string): IPromise<number>;
  remove(key: string): void;
}
  • O createStorageService cria e retorna uma instância do ILocalVisualStorageService, na verdade, MockIStorageService. 
    function createStorageService(): ILocalVisualStorageService;

MockIEventService

import powerbi from "powerbi-visuals-api";
import IVisualEventService = powerbi.extensibility.IVisualEventService;
import VisualUpdateOptions = powerbi.extensibility.VisualUpdateOptions;

class MockIEventService implements IVisualEventService {
      renderingStarted(options: VisualUpdateOptions): void;
      renderingFinished(options: VisualUpdateOptions): void;
      renderingFailed(options: VisualUpdateOptions, reason?: string): void;
}
  • O createEventService cria e retorna uma instância do IVisualEventService, na verdade, MockIEventService. 
    function createEventService(): IVisualEventService;

Utilitários

Os utilitários incluem métodos auxiliares para testes de unidade dos visuais do Power BI, incluindo auxiliares relacionados a cores, números e eventos.

  • O renderTimeout retorna um tempo limite.

    function renderTimeout(fn: Function, timeout: number = DefaultWaitForRender): number

  • O testDom ajuda a definir um acessório em testes de unidade.

    function testDom(height: number | string, width: number | string): JQuery

    Exemplo:

    import { testDom }  from "powerbi-visuals-utils-testutils";
describe("testDom", () => {
    it("should return an element", () => {
        let element: JQuery = testDom(500, 500);
        expect(element.get(0)).toBeDefined();
    });
});

  • getSolidColorStructuralObject

    function getSolidColorStructuralObject(color: string): any

    Retorna a seguinte estrutura:

    { solid: { color: color } }

  • O assertColorsMatch compara objetos RgbColor analisados com base em cadeias de caracteres de entrada.

    function assertColorsMatch(actual: string, expected: string, invert: boolean = false): boolean

  • O parseColorString analisa a cor com base na cadeia de caracteres de entrada e a retorna no RgbColor da interface especificada.

    function parseColorString(color: string): RgbColor

  • getRandomNumbers gera um número aleatório usando os valores mínimo e máximo. Você pode especificar exceptionList e fornecer uma função para a alteração do resultado.

    function getRandomNumber(
    min: number,
    max: number,
    exceptionList?: number[],
    changeResult: (value: any) => number = x => x): number

  • O getRandomNumbers fornece uma matriz de números aleatórios gerados pelo método getRandomNumber com os valores mínimo e máximo especificados.

    function getRandomNumbers(count: number, min: number = 0, max: number = 1): number[]

Os métodos a seguir são escritos para a simulação de eventos de página da Web em testes de unidade.

  • O clickElement simula um clique no elemento especificado.

    function clickElement(element: JQuery, ctrlKey: boolean = false): void

  • O createTouch retorna um objeto Touch para ajudar a simular um evento de toque.

    function createTouch(x: number, y: number, element: JQuery, id: number = 0): Touch

  • O createTouchesList retorna uma lista de eventos do Touch simulados.

    function createTouchesList(touches: Touch[]): TouchList

  • O createContextMenuEvent retorna MouseEvent.

    function createContextMenuEvent(x: number, y: number): MouseEvent

  • O createMouseEvent cria e retorna MouseEvent.

    function createMouseEvent(
    mouseEventType: MouseEventType,
    eventType: ClickEventType,
    x: number,
    y: number,
    button: number = 0): MouseEvent

  • createTouchEndEvent

    function createTouchEndEvent(touchList?: TouchList): UIEvent

  • createTouchMoveEvent

    function createTouchMoveEvent(touchList?: TouchList): UIEvent

  • createTouchStartEvent

    function createTouchStartEvent(touchList?: TouchList): UIEvent

Os métodos a seguir são usados para simular eventos D3 em testes de unidade.

  • O flushAllD3Transitions força a conclusão de todas as transições D3.

    function flushAllD3Transitions()

    Observação

    Normalmente, as transições de atraso zero são executadas após um atraso instantâneo (<10 ms), mas isso poderá causar uma pequena cintilação se o navegador renderizar a página duas vezes. Uma vez no final do primeiro loop do evento e novamente logo após o primeiro retorno de chamada do temporizador.

    Essas cintilações são mais perceptíveis no IE e com um grande número de modos de exibição da Web e não são recomendadas para o iOS.

    Ao liberar a fila do temporizador no final do primeiro loop do evento, você poderá executar qualquer transição de atraso zero imediatamente e evitar a cintilação.

Os seguintes métodos também estão incluídos:

function d3Click(element: JQuery, x: number, y: number, eventType?: ClickEventType, button?: number): void
function d3MouseUp(element: JQuery, x: number, y: number, eventType?: ClickEventType, button?: number): void
function d3MouseDown(element: JQuery, x: number, y: number, eventType?: ClickEventType, button?: number): void
function d3MouseOver(element: JQuery, x: number, y: number, eventType?: ClickEventType, button?: number): void
function d3MouseMove(element: JQuery, x: number, y: number, eventType?: ClickEventType, button?: number): void
function d3MouseOut(element: JQuery, x: number, y: number, eventType?: ClickEventType, button?: number): void
function d3KeyEvent(element: JQuery, typeArg: string, keyArg: string, keyCode: number): void
function d3TouchStart(element: JQuery, touchList?: TouchList): void
function d3TouchMove(element: JQuery, touchList?: TouchList): void
function d3TouchEnd(element: JQuery, touchList?: TouchList): void
function d3ContextMenu(element: JQuery, x: number, y: number): void

Interfaces auxiliares

A interface e as enumerações a seguir são usadas na função auxiliar.

interface RgbColor {
    R: number;
    G: number;
    B: number;
    A?: number; 
}

enum ClickEventType {
    Default = 0,
    CtrlKey = 1,
    AltKey = 2,
    ShiftKey = 4,
    MetaKey = 8,
}

enum MouseEventType {
    click,
    mousedown,
    mouseup,
    mouseover,
    mousemove,
    mouseout,
}

Conteúdo relacionado

Para escrever testes de unidade para os visuais do Power BI baseados no webpack e teste de unidade com karma e jasmine, confira o Tutorial: adicionar testes de unidade a projetos de visuais do Power BI.