concordialang-healer

✓ Autocura de especificações escritas em Concordia

Conteúdo

1. Visão Geral
2. Plugins
3. Instalação
4. Configuração
5. Executando
6. Banco de dados suportados
7. Plugins padrão
8. Criando heurísticas
9. Criando parser

Visão Geral

Ao usar concordialang-healer seus testes em Concordia serão capazes de se recuperar ao se deparar com o erros decorridos por seletores defasados.

A ferramenta fornece:

1. um servidor websocket responsável por:

   • se comunicar com o banco de dados e guardar informações dos elementos de IU;

   • receber solitações de cura e fornecer um novo seletor para o elemento defasado atráves de heurísticas pré-definidas.

2. um plugin Concordia responsável por:

   • executar plugin Concordia para gerar e executar testes com autocura;

   • solicitar permissão ao usuário para adaptação;

   • curar as especificações descritas em Concordia (arquivos .feature).

O processo de cura acontece através de dois momentos:

1. Quando o elemento é encontrado suas informações são guardadas para posterior consulta

2. Quando o elemento não é encontrado as informações guardadas são utilizadas para curar o elemento

Elemento encontrado

1. Os dados do elemento são capturados e armazenados para posterior consulta - nome da feature, seletor e informações atuais do elemento (como propriedades e posição na IU)

2. Elemento não encontrado

1. O erro é capturado e a cura é solicitada através da feature, seletor, conteúdo atual da IU (em string) e caminho para o teste em execução

2. As informações anteriores do elemento são consultadas

3. O parser é utilizado para transformar a IU de string para um documento que possa ser consulta pelas heurísticas

4. As heurísticas são executadas

5. É calculado o elemento com melhor pontuação, respeitando o minimumScore

6. O parser é utilizado para obter um seletor para o elemento escolhido

7. O novo seletor e injetado no teste e a execução continua - sem precisar parar o teste

8. Após a execução, será solitado a permissão para adaptar a especificação com o novo seletor

Plugins

Para funcionar, a ferramenta necessidade de 3 tipos de plugins:

1. Gerador de testes com autocura
2. Heurística
3. Parser

Gerador de testes com autocura

Esse plugin é usado para geração e execução dos testes através do Concordia com a opção de autocura. O plugin deve ser capaz de:

• enviar as informações dos elementos de IU durante os testes;

• solicitar cura ao se deparar com um seletor não encontrado (erro de "ElementNotFound");

• injetar o novo seletor fornecido pelo servidor em tempo de execução dos testes.

Heurística

Esse plugin é responsável por procurar elementos na IU atual que mais se aproximam do elemento anterior - que está com o seletor defasado.

Ex.: Procurar elementos que possuam o id username no DOM.

Parser

Esse plugin é responsável por:

• transformar a IU atual de string para um documento que possa ser consultado pelas heurísticas;
  Ex.: Transformar HTML string em DOM.
• gerar um seletor para um determinado elemento.
  Ex.: #username para o elemento <input type="text" name="username" id="username"/>

Instalação

Você precisa ter instalado o Concordia no seu projeto

Instalando o pacote através do npm:

npm install concordialang-healer --save-dev

Além disso, você precisará instalar:

• o driver do banco de dados - banco de dados suportados

• as heurísticas que for utilizar - instalando heurísticas

• o parser - instalando parser

• o plugin para geração e execução de testes com autocura - instalando gerador de testes com autocura

👉 Nota.: Você também pode instalar pelo yarn

Configuração

Adicione o concordialang-healer como plugin nas configurações do Concordia (geralmente .concordiarc).

{
  "plugin": "concordialang-healer"
}

Inicialize o arquivo de configuração do concordialang-healer:

npx concordia-healer --init

O arquivo .healerrc.json será gerado com as configurações padrões.

minimumScore

Um limiar minímo para que o elemento seja considerado no processo de cura.

O elemento será rejeitado se obtiver score menor.

obrigatório

{
  "minimumScore": 0.5
}

server

As opção para o serviço websocket:

• port: a porta onde o serviço irá rodar - obrigatório
• host: localhost por padrão

{
  "server": {
    "port": 3000
  }
}

database

As opções para o serviço de banco de dados:

• type: o tipo de banco de dados a ser utilizado - ver opções - obrigatório
• dbName: o nome do banco de dados - precisa ser criado no seu banco - obrigatório
• host: localhost por padrão
• port: a porta onde está rodando o serviço do banco de dados
• user: o usuário do banco de dados
• password: a senha para o usuário fornecido

{
  "database": {
    "type": "postgresql",
    "dbName": "concordia_healer",
    "host": "localhost",
    "port": 5432,
    "user": "<user>",
    "password": "<password>"
  }
}

plugin

O plugin para geração de testes através do concordia com opção de cura.

• from: a localização do plugin - obrigatório
• options: parâmetros a serem passados para o plugin - somente se ele tiver essa opção

{
  "plugin": {
    "from": "@concordialang-healer/codeceptjs-playwright/dist",
    "options": {}
  }
}

heuristics

A opção heuristics deve ser um array contendo as heurísticas a serem usadas para curar o elemento.

As heurísticas serão executadas na ordem em que aparecem no array.

Cada entrada de heurísticas possui:

• name: o identificador da heurística - obrigatório
• from: a localização da heurística - obrigatório
• options: parâmetros a serem passadas para a heurística - somente se a heurística possuir opções

{
  "heuristics": [
    {
      "name": "by-id",
      "from": "@concordialang-healer/heuristics-web/dist/heuristics",
      "options": {}
    }
  ]
}

parser

Esse opção deve fornecer um plugin que será usado para:

• transformar a IU atual em documento que pode ser analisado pelas heurísticas;
• gerar um seletor para o elemento melhor pontuado pelas heurísticas.

As opções a serem fornecidas são:

• from: a localização do plugin - obrigatório
• options: parâmetros a serem passados para o plugin - somente se ele tiver essa opção

{
  "healer": {
    "from": "@concordialang-healer/heuristics-web/dist/healer",
    "options": {}
  }
}

Executando

Você precisa iniciar o servidor antes de rodar os testes com o Concordia.

npx concordia-healer server

O servidor será executado na porta determinada pela sua configuração.

Agora você pode executar os testes com Concordia e aproveitar a opção de autocura! 😉

Exemplo

Que tal testar a ferramenta?

Basta analisar o projeto de exemplo para ver a ferramenta em funcionamento. 👍

Banco de dados suportados

Atualmente a ferrementa suporta os seguintes banco de dados:

• sqlite

  npm install @mikro-orm/sqlite --save-dev

• postgresql

  npm install @mikro-orm/postgresql --save-dev

• mariadb

  npm install @mikro-orm/mariadb --save-dev

• mysql

  npm install @mikro-orm/mysql --save-dev

Plugins Padrão

A ferramenta fornece plugins para todos os tipos.

Instalando gerador de testes com autocura

Ver o pacote @concordialang-healer/codeceptjs-playwright.

npm install @concordialang-healer/codeceptjs-playwright --save-dev

Instalando heurísticas

Ver o pacote @concordialang-healer/heuristics-web.

npm install `concordialang-healer/heuristics-web --save-dev

Instalando parser

Mesmo pacote @concordialang-healer/heuristics-web anterior.

Criando heurísticas

As heurísticas podem ser criada em Javascript ou Typescript (recomendado).

1. Crie um pacote

As heurísticas podem ser exportados unicamente ou em conjunto (array), o concordialang-healer utiliza o nome da heurística para encontrá-la.

2. Crie uma função

Deve ser uma função com um parâmetro opcional, podendo receber opções para configuração.

Deve retornar um objeto com as seguintes propriedades:

• name: Nome da heurística, será utilizado para identificar a heurística

• run: Método responsável por executar a heurística

Se estiver usando Typescript é recomendado implementar o tipo Heuristic.

2. Método run

Recebe um objeto:

• element: o elemento defasado - UIElement

• source: o conteúdo atual da IU - já transformado pelo parser

Retorna um objeto (HeuristicResult):

• elements: os elementos que se enquadram na heurísticas com score - ScoredElement
• weight: o peso da heurística - number

👉 Nota: Você também pode retornar um array de HealingResult, caso seja necessário definir pesos diferentes

Exemplo:

Heurística para encontrar elementos pela tag em interfaces HTML.

import { Heuristic } from '@concordialang-healer/common';

const byTag: Heuristic = () => ({
  name: 'by-tag',
  run: ({ element, source }) => {
    const locator = element.content.tag;
    const foundElements = Array.from(source.querySelectorAll(locator));

    if (!foundElements?.length) {
      return [];
    }

    return {
      weight: 1 / foundElements.length,
      elements: foundElements.map((node) => ({
        node,
        locator,
        score: 1,
      })),
    };
  },
});

export default byTag;

Criando plugin parser

O parser pode ser criado em Javascript ou Typescript (recomendado).

1. Crie um pacote

O pacote deve exportar a função parser.

2. Crie uma função

Deve ser uma função com um parâmetro opcional, podendo receber opções para configuração.

Deve retornar um objeto com as seguintes propriedades:

• transform: Transforma a interface IU atual de string para um documento que possa ser consultado pelas heurísticas. Ex.: html para DOM

• toLocator: Gera seletor para um determinado elemento

Se estiver usando Typescript é recomendado implementar o tipo Parser.

Exemplo:

import { Parser } from '@concordialang-healer/common';
import { JSDOM } from 'jsdom';
import uniqueSelector from 'unique-selector';

const parser: Parser = () => ({
  transform: ({ source }) => ({
    source: new JSDOM(source.trim()).window.document,
  }),
  toLocator: ({ healing }) =>
    uniqueSelector(healing.node, {
      selectorTypes: ['ID', 'Class', 'Attributes', 'Tag', 'NthChild'],
    }),
});

export default parser;

Isso é tudo pessoal!

Caso encontre algum erro durante ou tenha alguma sugestão, publique uma issue em https://github.com/concordialang/healer/issues.

Obrigado e até mais! 👋