Storybook

Configuração

Foi bem facil configurar ele para rodar com o projeto template do svelte.

Com riot não foi possível utilizar ele, pelo que identifiquei, ele só funciona com a versão 3 do riot. Ele fica pedindo os compiladores e outros pacotes que foram originalmente feitos para o riot 3.

Ainda testando com riot, parece que ele tem problemas em executar quando o projeto está com webpack 5, quando mudei para o rollup o projeto, o erro não aparecia mais. Como o projeto svelte estava com rollup foi tranquilo.

Nos pontos abaixo foi utilizado a configuração svelte + rollup.

Configurar svelte com scss deu trabalho, mas deu certo. - tive de mudar o webpack4 p/ webpack5 - corrigir um bug que aparece no svelte quando adiciona essa webpack 5 - e também que adicionar o plugin de scss deles - https://github.com/storybookjs/presets/issues/220

Configurar svelte com jest também deu trabalho, o bug estava na versão do node, ao atualizar para o 14 tudo funcionou normalmente. - em resumo o problema surgiu ao tentar colocar o jest processar typescript dentro dos componentes, com o preprocessor - o curioso é que o transformador do svelte utilizado e demais libs, aceitavam nodejs v12

considerações iniciais

A documentação é boa, mas tem inconsistência e falta algumas coisas estarem documentadas na página oficial. Antes de iniciar essa leitura que trata de coisas que vão além da documentação, indico que seja lido: - o tutorial inicial - o get started - uma rápida olhada em tudo das docs - E mantenha em mente que boa parte da documentação está no repo do addon em si, e no github deles - https://github.com/storybookjs/storybook/blob/next/MIGRATION.md - https://github.com/storybookjs/storybook/tree/next/addons/docs

Tipos de arquivos p/ descrever stories

• Tem 3 formas de escrever uma story, com js, svelte ou mdx. Mdx é melhor para o addon de documentação, mas a notação é confusa, mistura jsx e markdown. Não sei qual usar. Usar todas pode aumentar o tempo para aprendizado.
• MDX requer mais código boilerplate para gerar o mesmo que um js ou svelte geraria sozinho
• A notação de svelte para decorator é bem mais intuitiva
• Podemos substituir um md por uma página mdx, sem stories.
• Vendo os adons dá p/ ver que o storybook foi pensado primeiramente para react, tem suporte para muitos outros frameworks mas o svelte é um q é mantido pela comunidade, então tem a maioria das features, mas não todas, o formato não está tão bem consolidade como o do react, mas considerando a crescente do svelte é seguro.

Pontos negativos

recursos do svelte nas diferentes notações

• até o momento só achei como usar slots usando a notação de svelte
  • se não for com notação svelte tem que fazer um wrapper
  • https://github.com/storybookjs/storybook/blob/main/examples/svelte-kitchen-sink/src/stories/views/ButtonView.svelte

recursos do storybook nas diferentes notações

• Utilizando svelte, não consigo fazer composição de args
  • https://storybook.js.org/docs/svelte/writing-stories/args#args-composition

[addon] docs

• Quanto utilizado o "args" e templates, se não declarado os controles ele consegue pegar sozinho, porém ele não indica qual seria o atributo padrão quando o props já tem um valor inicial nos controles, mas na doc mostra. Se sempre for declarado tudo, isso não é um problema.
• Se utilizado slots, a documentação indica que existe um slot, mas o código auto gerado não mostra os slots
• Alguns recursos do svelte não são auto documentados, como por exemplo, exportar funções, eventos disparados pelo modificador de reatividade, tipagem mais complexas, tipagem da função.
  • o curioso disso é que a lib que o storybook usa 'sveltedoc-parser' consegue dar parser de algumas tipagens mais complexas
    • deveria mostrar assim: https://next--storybookjs.netlify.app/official-storybook/?path=/docs/docs-argrow--complex-object
• Quando colocado TS é necessário adicionar preprocessors, assim como p/ scss, entretanto para que o TS não cague o doc tem ser utilizado da forma correta (que não está nada documentado), mas mesmo adicionado da forma correta, ele ainda não infere os tipos direto do typescript, tem q ser do docstring
  • https://github.com/storybookjs/storybook/issues/16609
  • https://github.com/storybookjs/storybook/issues/13902
  • https://github.com/storybookjs/storybook/issues/12754#issuecomment-779652299
  • o esquema é declarar duas vezes, tanto no TS no compoente quando na story ou docstring
  • acho que esse é um problema da lib 'sveltedoc-parser' que o svelte usa para analisar estaticamente os tipos, hoje ela só comporta docstring
• Para otimizar o uso do auto gerador o ideal seria, para toda props sempre ter boas stories, assim fica "ok" consultar o formato, principalmente em objetos complexos. Mesmo o autogerador não conseguindo inferir os tipos e documentar. Também é possível documentar na mão, mas o formato não é interessante, além de ser necessário fazer na mão.

[addon] storyshots

• Até o momento só consegui fazer funcionar o storyshots com a notação .js ou .ts, abri uma issue p/ ver no que dá: https://github.com/storybookjs/addon-svelte-csf/issues/35
  • no pior dos casos podemos fazer testes somente para usar snapshots, mas ai é mais uma coisa p/ manter: storybook, testes, snapshots, componente em si PARECE QUE O STORYSHOTS SEMPRE QUEBRA POR CONTA DAS CLASSES AUTO INSERIDAS PELO SVELTE

[addon] playwright

• Em teoria feito para funcionar com react
• só funciona com a notação js e ts de stories
• Não tem muitos download por semana, só 317
• Não é oficial
• Roda com a versão 6.3 do storybook, que no momento é a ultima mesmo
• tem dependencia de coisa legada do storybook
• não roda com node 14, o que conflita com svelte+jest
• Nao consegui rodar nem com react nem com svelte, nem seguindo o exemplo deles

[addon] accessibility

• foi facil de configurar, funcionou perfeitamente na stack atual, com webpack ts, e tudo mais
• inclusive atualizar o feedback quando mudamos os props ao vivo
• único ponto estranho é que o botão mais inacessível apontou o erro de acessibilidade em 'incomplete' e não em 'violations'. Não entendi o porque
• ele também aponta com highlight na tela o que está errado, o que é bem maneiro

[addon] interactions

• só roda nas versões 6.4-beta, nem testei ainda
• acho q não vale a pena pegar versão beta, ainda mais usando svelte

[addon] creevey

• não é oficial, mas parece um plugin bem movimentado, mas não tanto quanto o loki
• usa docker para instalar as dependências, então como pre requisito tem q ter docker instalado e liberado para o usuário local rodar
• tem q saber lidar com docker
• tem q rodar o storybook primeiro
• só roda com notação ts
• funcionou perfeitamente na stack atual
• não tem feature nativa para lidar com responsividade, mas podemos utilizar o selenium para mudar o viewport manualmente, pois ele entrega a instância do drive do navegador nas stories
• segundo doc deles, tem um problema em tentar executar o projeto dentro de um docker, talvez pq a própria ferramenta precisa acessar o docker
• a quantidade de imagens que ele gera pode ser um problema ter isso salvo no git
• a ferramenta de diff funciona muito bem na maioria dos casos, mas em alguns momentos ele renderiza o componente incorretamente, o que pode dificultar o uso em CI por não ser determinístico.

[addon] fixtures

• Não possui suporte oficial a svelte
• Não chegamos a testar ele, pois de forma simples o que ele faz é entregar uma interface para poder selecionar presets de props. Isso força com que os componentes de página sejam dummy components, ou seja, não fazem fetchs, o que pode ser interessante em termos de modularização, mas pode dificultar o desenvolvimento e comprometer a flexibilidade.
• Imagine um formulário que tem diversos selects ditados por fetchs, poderiamos fazer os fetchs aos poucos, somente quando o usuário abrir o um select, mas como ele seria um dummy component, um wraper que não a página e nem o formulário deve fazer todos os fetchs e passar para os componentes em cascata.

outros

• Os apontamentos de erros geralmente não indicam a linha de código errada corretamente, indica a linha de código do svelte depois de passar por processamento, ou até mesmo um erro no webpack. Dificulta muito o debug em muitos casos. As vezes é necessário renderizar o componente e rodar com o rollup no lugar do storybook para ver qual é o erro.
• A documentação para uso com svelte+ts é bem pouca

Outras paradas

• O estado global do componente não faz parte da interface do componente, entretanto, se um componente esperar que deva existir um estado global x, isso deve ser documentado manualmente. Quanto a testes do estado global, deve ser tratado como um arquivo js normal, e não um componente.
• A função avançada do svelte 'getContext' faz parte da interface de um componente, e "burla" o sistema de props. É de extrema necessidade que o componente que espera que exista um determinado contexto tenha isso documentado manualmente, e o componente que define um determinado contexto defina isso manualmente. Utilizando typescript é importante que seja definido a interface do contexto que será definido ou obtido.

• Testes de funções normais '.js, .ts' são testadas normalmente, o storybook não intefere nisso

• Tem nada a ver com storybook o que vou falar aqui:

  • testes de integração ou e2e que requerem o browser são bem mais lentos que renderizar um fake dom e testar com jest.
  • testar componentes, com visual ou snapshots cai no problema de regressão, isso é, se header usa button e button falha, header vai falhar. Isolar header (mockar a dependência de outro componente), para evitar isso não é trivial, muitas vezes não há o que colocar no lugar de forma simples, ou a interface é sensível (requer que qualquer mudança no botão seja espelhada no header e no mockup). Testar somente o comportamento dos componentes tem um pouco mais de resistência a mudança das dependências, mas somente se o componente já possui um comportamente bem definido, se este comportamento for volátil, a escrita de testes se torna mais custosa. Em resumo:
    • snapshots e testes visuais tem mais problemas de regreção e devem ser atualizados constantemente
    • snapshots precisam ser revisados com frequência, no processo de revisão dos commits, pq o update atualiza tudo e não só um snapshot, o que torna facil dar update acidentalmente
    • teste unitários testam o comportamento core, mas perdem pequenos problemas de regreção como por exemplo a interface entre um componente dependente.
  • https://benmccormick.org/2016/09/19/testing-with-jest-snapshots-first-impressions/

TODO

• Ver como atualizar o projeto que estou testando p/ o 6.4
• Testar o addon interaction p/ 6.4 e ver se n quebra o creevey (talvez funcione como um e2e?)
• Ver como fica tipar parâmetros mais complexos, interfaces e classes
• Ver como o creevey funciona no CI
• Ver como fica testes quando se tem interatividade, teste de ações

Conclusão

• O bagulho é muito bom
• Svelte ainda é novo, mas tem boa parte das features, e funciona bem com a versão atual
• O formato ideal para escrevermos histórios é na notação js
  • tem menos boilerplate que o svelte, tem mais features, e mais documentação
  • para utilizar slots temos que fazer um componente wrapper, o que faz com que percamos o snippet de código, mas tudo bem
• O formato mdx é interessante, mas é muito manual, quando for necessário fazer uma página de doc mais robusta, pode ser utilizado ele.
• A ideia do uso desse framework é criar componentes dirento documentando e fazendo testes, e não precisar ler o código para entender como o componente funciona. Em segundo, conseguir testar nele mesmo os componentes.
• O uso do storybook não elimina o jest para testes de classes e funções

Artigo - tópicos

Guia geral: - estudos - o que buscamos - o que testamos, e o que achamos de cada um - o que selecionamos e o pq - o que ainda queremos adicionar, mas ainda não estudamos o como fazer, ou não achamos soluções ainda

• o que tem na nossa stack atual

  • objetivo da nossa stack
    • ser rápida de codar, limpa, garantir qualidade, codar menos testes...
  • o que tem na stack, porque escolhemos (a nivel macro) usar essas ferramentas?
    • passar brevemente no que utilizamos do storybook e linkar para o detalhado
    • passar brevemente no que utilizamos de teste e linkar para o detalhado
  • quais as versões?
  • como codar nesta stack? linkar fluxo de desenvolvimento
  • problemas que sabemos na stack
    • import dentro da tag do svelte não é resolvido pelo rollup e sim pelo preprocesso, o que resulta em duplicidade de código
  • O que ainda queremos acrescentar
  • falar explicitamente quais bundler temos p/ não ter confusão

• storybook

  • versões
  • o que é
  • qual o nosso objetivo com ele, link para nossa stack
  • foco do texto não é ensinar a usar, e sim a experiência que tivemos ao colocar ele junto com svelte, e o que selecionamos para utilizar
  • por onde começar a estudar
  • tl;dr (conclusão do que funciona com o svelte e link para o fluxo de desenvolvimento)
  • configurações para uso na stack (svelte, ts, scss, ...)
  • formatos de escrita e seus problemas, qual selecionamos
  • addons que funcionaram e seus propósitos
    • na parte de testes, jogar para o estudo de testes
  • link para o nosso fluxo de desenvolvimento
  • o que ainda queremos acrescentar (melhorias p/ o próprio storybook até)

• fluxo de desenvolvimento

  • configurações iniciais para utilizar a stack em toda a sua glória, (lint, ...)
  • como codar:
    • diclamer: tudo aqui é um direcionamento e não regra
      • não temos como cobrir todos os casos
      • vale o bom senso
    • organização de pastas, boas práticas css, js, lint, ...
    • arquivos que podemos criar
      • componentes vs páginas
      • fluxo de uma request
        1. função que acessa a api:
           1. faz a request
           2. lida com as possibilidades de retorno: 200, 404, .... e retorna algo mais alinhado com o app
        2. algum helper da página, que pode ser testado isoladamente (pode ser testado, apenas mocando a entrada, direto no jest):
           1. transforma o retorno 200 em algum outro formato de dado, ou lida com o fato de não ter o dado ou ter dado errado
        3. o app via props (pode ser mocado, apenas passando uma props que é uma promise, direto no storybook):
           1. recebe uma promise
           2. espera ser resolvida
           3. e joga joga na tela se deu certo
           4. informa o erro se deu errado
    • uso de estados globais
    • quando usar variaveis globais css
    • stoybook
      • como criar as stories, até que ponto podemos criar stories?
        • criar stories para todo o tipo de interação?
      • documentações manuais, ...
    • testes
      • link para detalhado do pq escolhemos fazer os testes assim
      • quais deles fazer, quando fazer, pq fazer?
      • testes visuais
      • mocks
  • link para fluxo de uso do git, deploy e staging e versionamento
  • o que ainda queremos acrescentar

• estilo de código

  • ref: https://awesomeopensource.com/project/voorhoede/riotjs-style-guide

• estudo de testes

  • tipos de testes
  • quais testes escolhemos fazer, e o pq, a que nível
  • quais ferramentas testamos, e quais selecionamos utilizar para cada tipo de teste
  • qual frequência cada teste deve ter, e a que nível
  • o que testar
  • como seguir no fluxo? link para parte de teste no fluxo de desenvolvimento
  • o que ainda queremos acrescentar

• como adicionar jest a um projeto svelte

• como adicionar storybook a um projeto svelte

• como converter nossa stack para um projeto mobile

• como adicionar lint? ts? rollup?

• documentar nosso padrão de código em ts e js

• documentar nosso padrão de código em scss

• documentar como transformar nossa stack p/ projeto em uma stack para pacotes npm

• tutorial montando a stack pedaço a pedaço, explicando o uso do fluxo

  • só svelte: explicar componentes
  • svelte + lint
  • svelte + ts
  • svelte + rotas: inserção da lib de rotas e explicar dinâmica com componentes e páginas
  • svelte + helpers: explicar reutilização de código
  • svelte + testes com jest: inserção do svelte e testar helpers e componentes
  • storybook: inserção do storybook e documentar componentes
  • svelte + fetchs no banco
  • svelte + websockets
  • mocks: mock de páginas e estado global
  • snapshots tests: explicar inserção de snapshots e exemplificar
  • screenshot tests: explicar inserção de screenshot e exemplificar
  • e2e testes: explicar inserção de e2e tests e exemplificar
  • bdd e tdd: explicar o que é e exemplificar