Teste de Starters

Nesta seção, você encontrará um guia sobre como criar e executar casos de teste para seus Starters.

Visão Geral

O que são teste de Starters

Assim como os testes de Plugins, o teste de Starters permitem que você crie testes unitários para os seus Starters. Dessa forma, os testes garantem que os Starters se comportarão conforme o esperado.

Quando você usa o comando stk create starter para criar um Starter, você encontrará uma estrutura de pastas de teste dentro dos arquivos gerados. Esta estrutura contém os testes unitários.

A estrutura de pastas começa com um diretório chamado "testes" e outros arquivos. Confira:

Pastas utilizadas nos testes

À seguir você encontra detalhes sobre cada pasta e seus objetivos:

Pasta tests/

Dentro do Starter uma pasta "tests" contém os casos de testes relacionados ao Starter. Dentro de cada caso de teste, você encontra a pasta expected. Confira a seguir:

expected/

Cada caso de teste possui uma pasta "expected" que deve conter todos os arquivos necessários para sua Aplicação ou Infraestrutura, como arquivos de projeto e códigos-fonte. Por exemplo, se o seu Starter inclui Plugins que adicionam um aplicativo Java ou uma implementação de Infraestrutura, a pasta "expected" deve conter os arquivos do projeto Java com todas as implementações relevantes.

Os arquivos de configuração gerados da Aplicação e Infraestrutura, gerados quando você cria uma Aplicação ou Infraestrutura não precisam ser adicionados na pasta expected.

Arquivos dos casos de teste

Cada caso de teste possui um manifesto no formato .yaml chamado test-case.yaml, que fornece informações para testar seu Starter.

Confira o test-case.yaml de um Starter:

schema-version: v2
kind: test
metadata: 
  name: my-app
  description: my-description
spec:
  type: starter
  plugins:
    - name: studio-slug/plugin-name
      alias: example-plugin-alias
      inputs: {}
    - name: studio2-slug/plugin2-name
      alias: example2-plugin-alias
      inputs: {}

Campos do arquivo teste-case.yaml

metadata:

Refere-se às informações necessárias ao criar umm Aplicação ou Infraestrutura. Consiste em dois campos:

• name: Representa o nome da Aplicação ou Infraestrutura que você deseja criar.

• description: Este é um campo opcional onde você pode descrever brevemente a Aplicação ou Infraestrutura.

spec:

• type: Este campo indica o tipo de manifesto, que é sempre "starter".

• plugins: Esta é uma lista de Plugins obrigatórios e opcionais para o Starter que você pretende testar. Cada Plugin da lista possui os seguintes campos:

• name: O nome e origem do Plugin são os mesmos do Starter. A origem é o nome do slug do Studio. A sintaxe é: studio-slug/plugin-name.

  • alias: O nome alternativo que é usado ao aplicar o Plugin.

  • inputs: O nome e valor de cada input do Plugin.

• connections: A lista de Connections Interfaces requeridas ou geradas pelo Plugin.

Criar casos de teste

Antes de começar

Você deve criar manualmente a estrutura a seguir e preencher os arquivos de casos de teste para Starters existentes que não possuem casos de teste. Confira:

Dentro da sua Stack, na pasta starters:

1. Crie a pasta de tests;
2. Dentro da pasta tests, crie a pasta com o nome do seu caso de teste, por exemplo, "test-case-001";
3. Dentro do seu caso de teste:

• Crie o arquivo test-case.yaml e cole o conteúdo em seu arquivo de teste:

basic starter test scaffold

schema-version: v2
kind: test
metadata: 
  name: my-app
  description: my-description
spec:
  type: starter
  plugins:
    - name: studio-slug/plugin-name
      alias: example-plugin-alias
      inputs: {}
    - name: studio2-slug/plugin2-name
      alias: example2-plugin-alias
      inputs: {}

4. Crie a pasta expected.

Preencher o teste do Starter

Com a estrutura de testes em seu Starter pronta, adicione os arquivos e preencha os inputs do seu Starter:

Passo 1. Adicione os arquivos da Aplicação ou Infraestrutura no caso de teste

Na pasta '/expected': Adicione nesta pasta uma cópia de todos os arquivos da sua Aplicação ou Infraestrutura, exceto os arquivos infra-spec.yaml e app-spec.yaml.

Passo 2. Preencha o arquivo test-case.yaml

No arquivo test-case.yaml do seu teste, confira os dados e preencha os inputs do seu teste de acordo com os Plugins do seu Starter.

Preencher inputs

Considere um Plugin do seu Starter com os seguintes inputs:

• O exemplo destaca os campos name: dos inputs que você deve adicionar ao caso de teste;

spec:
  # . 
  # .
  # . Other spec fields above...
  inputs:
    - label: Database name
      name: database_name
      type: text
      required: true

O arquivo de teste preenchido deve se parecer com um dos exemplos, onde a sintaxe das entradas deve ser:

• inputs

inputs:
  input_name: "input value"

Exemplo:

Este é um exemplo para demonstrar como preencher corretamente os inputs em seu caso de teste. Por favor, não use este exemplo para seus projetos.

schema-version: v2
kind: test
metadata: 
  name: my-app
  description: my-description
spec:
  type: starter
  plugins:
    - name: studio-slug/plugin-name
      alias: example-plugin-alias
      inputs:
        database_name: "The name provided for the database_name input"

Preencher requires e generates Connections

Se o Plugin em seu Starter gera ou requer Connections Interfaces, você deverá adicioná-las ao caso de teste. Considere os exemplos:

Plugin com Connection requerida

Plugin de Infraestrutura que requer um bucket s3. Este é um exemplo para demonstrar como preencher corretamente os campos das Connections do seu teste de Starter. Por favor, não use este exemplo em seus projetos.

schema-version: v3
kind: plugin
metadata:
  name: plugin-infra-req-s3
  display-name: plugin-infra-req-s3
  description: Plugin that requires S3
  version: 0.0.1
  picture: plugin.png
spec:
  type: infra
  compatibility:
    - python
  docs: #optional
    pt-br: docs/pt-br/docs.md
    en-us: docs/en-us/docs.md 
  single-use: False
  runtime:
    environment:
      - terraform-1-4
      - aws-cli-2
      - git-2
  repository: https://github.com
  technologies: # Ref: https://docs.stackspot.com/create-use/create-content/yaml-files/plugin-yaml/#technologies-1
    - Api
  inputs:
    - label: Connection interface for your aws-s3-req-alias
      name: aws-s3-req-alias
      type: required-connection
      connection-interface-type: aws-s3-conn 
  stk-projects-only: false

Plugin que gera Connections

Plugin de Infraestrutura que gera um bucket s3. Este é um exemplo para demonstrar como preencher corretamente os campos das Connections do seu teste de Starter. Por favor, não use este exemplo em seus projetos.

schema-version: v3
kind: plugin
metadata:
  name: plugin-infra-gen-s3
  display-name: plugin-infra-gen-s3
  description: Plugin to generate S3
  version: 0.0.1
  picture: plugin.png
spec:
  type: infra
  compatibility:
    - python
  docs: #optional
    pt-br: docs/pt-br/docs.md
    en-us: docs/en-us/docs.md
  single-use: False
  runtime:
    environment:
      - terraform-1-4
      - aws-cli-2
      - git-2
  technologies: # Ref: https://docs.stackspot.com/create-use/create-content/yaml-files/plugin-yaml/#technologies-1
    - Api
  stk-projects-only: false
  inputs:
    - label: Digite o nome da connection s3
      name: bucket_s3
      type: generated-connection
      connection-interface-type: aws-s3-conn
      outputs:
         - from: aws-s3-alias-arn
           to: arn
         - from: aws-s3-alias-bucket_name
           to: bucket_name

Para o exemplo do caso de teste, confira a sintaxe nos exemplos:

Caso de teste com Connection requerida

schema-version: v2
kind: test
metadata: 
  name: my-app
  description: my-description
spec:
  type: starter
  plugins:
    - name: studio-slug/plugin-name
      alias: example-plugin-alias
      inputs:
        database_name: "The name provided for the database_name input"
        aws-s3-req-alias: 
          selected: my-s3-req
          outputs:
            arn: "my-s3-arn"
            bucket_name: "my-bucket-name"

Caso de teste com Connection gerada

schema-version: v2
kind: test
metadata: 
  name: my-app
  description: my-description
spec:
  type: starter
  plugins:
    - name: studio-slug/plugin-name
      alias: example-plugin-alias
      inputs:
        database_name: "The name provided for the database_name input"
        bucket_s3:
          selected: my-s3-req
          outputs:
            arn: "aws-s3-alias-arn"
            bucket_name: "aws-s3-alias-bucket_name"

Run Starter tests

Execute os testes dentro da pasta do seu Starter. Para executar os testes, acesse sua Stack e depois a pasta "starters" e execute os comandos de acordo com os testes que deseja executar:

Executar todos os casos de testes do Starter

Run the command:

stk test starter 

Executar um caso de teste específico do Starter

Execute o comando com o nome da pasta de teste:

stk test starter [test-case-name]

Exemplo:

stk test starter test-case-connection-gen001

Executar os testes com o filtro --verbose

Você pode usar a opção --verbose para detalhar o resultado dos casos de teste em seu terminal.

Exemplos:

stk test starter --verbose

stk test starter test-case-connection-gen001 --verbose

Cenários de erro e testes ignorados

Durante a execução dos casos de teste, é fundamental que você identifique rapidamente os erros encontrados em seus Starters. Confira os erros mapeados e cenários onde seus Starters devem ser ajustados.

Erros mapeados no Starter:

• Código: STK_MESSAGE_BUSINESS_EXCEPTION_FOLDER_HAS_NO_TESTS_FOLDER_ERROR

Cenário: Quando você não encontrou a pasta tests;

• Código: STK_MESSAGE_BUSINESS_EXCEPTION_FOLDER_HAS_NO_TESTS_FOUND_ERROR

Cenário: Quando você não encontrou casos de teste na pasta tests;

• Código: STK_MESSAGE_BUSINESS_EXCEPTION_TEST_STARTER_INVALID_STARTER_MANIFEST_ERROR

Cenário: Quando não foi possível converter o manifesto do Starter (starter.yaml), por ser inválido;

• Código: STK_MESSAGE_BUSINESS_EXCEPTION_TEST_STARTER_STACK_NOT_FOUND_ERROR

Cenário:Quando o manifesto da Stack (stack.yaml) não foi encontrado nos diretórios raiz do Starter;

• Código: STK_MESSAGE_BUSINESS_EXCEPTION_TEST_STARTER_INVALID_STACK_MANIFEST_ERROR

Cenário: Quando não foi possível converter o manifesto da Stack (stack.yaml), por ser inválido;

• Código: STK_MESSAGE_BUSINESS_EXCEPTION_MISSING_REQUIRED_INPUTS_ERROR

Cenário: Quando os inputs necessários não estão incluídos no manifesto do caso de teste (test-case.yaml);

• Código: STK_MESSAGE_BUSINESS_EXCEPTION_TEST_STARTER_NO_TESTS_FOUND_WITH_TEST_NAME_ERROR

Cenário: Quando nenhum caso de teste com o nome desejado foi encontrado;

Testes ignorados:

• Quando a pasta expected não existe no diretório do caso de teste;
• Quando a pasta expected estiver vazia;
• Quando o manifesto do caso de teste (test-case.yaml) é inválido;
• Quando o manifesto do caso de teste (test-case.yaml) não pôde ser convertido.

Falha do caso de teste ao criar uma Aplicação ou Infraestrutura com o Starter:

• Quando os Plugins necessários não estão incluídos no manifesto do caso de teste (test-case.yaml);
• Quando o(s) Plugin(s) foram declarados no manifesto do caso de teste, mas não fazem parte da Stack (stack.yaml);
• Quando os inputs necessários não estão incluídos no manifesto do caso de teste (test-case.yaml);
• Quando o(s) input(s) não seguem o pattern (regex) definido no input;
• Quando as Connections necessárias não são declaradas no manifesto do caso de teste;
• Quando ocorre um erro inesperado durante a criação do app/infra;

Falha do caso de teste ao validar arquivos gerados:

• Quando o Starter gerou um arquivo inesperado;
• Quando o Starter gerou uma pasta inesperada;
• Quando o Starter não gerou a pasta esperada;
• Quando o Starter não gerou o arquivo esperado;
• Quando ocorre uma falha inesperada durante a validação dos arquivos gerados.

Falha do caso de teste ao validar conteúdo dos arquivos gerados:

• Quando o Starter gerou uma linha com conteúdo diferente do esperado;
• Quando o Starter gerou menos linhas que o esperado;
• Quando o Starter gera mais linhas que o esperado.