DEV Community: Eduardo Oliveira

HTMX: por que eu uso?

Eduardo Oliveira — Wed, 19 Jun 2024 23:29:44 +0000

Nos últimos dias surgiram diversos tweets com opiniões, indicações, ou pedindo textos de referência sobre o uso do HTMX. Optei pelo uso do HTMX em alguns projetos, inclusive em produção, e pela falta de conteúdos mostrando usos reais da biblioteca, decidi começar a escrever. Esse texto, em específico, nasceu de alguns desses questionamentos do twitter.

Conteúdos

Conteúdos
Introdução
O que é o HTMX?
Contexto e Motivos pela escolha
- 1. Template Engine
- 2. Django-Admin
- 3. Autenticação e Permissão
- 4. Funcionalidades do Django
- 5. Escopo
Alguns contrapontos
Quer dizer, então, que agora eu só uso HTMX?

Introdução

Esse texto foi inspirado por uma publicação do Mario Souto (omariosouto) no twitter ao questionar sobre a quantidade de gente indicando HTMX recentemente e se essas pessoas estavam usando HTMX em produção.

O tweet pode ser visto abaixo:

// Detect dark theme var iframe = document.getElementById('tweet-1803414625276305704-138'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1803414625276305704&theme=dark" }

Tenho trabalhado com HTMX (Django + HTMX, pra especificar a stack), inclusive em produção (Veja o texto Django, Htmx e React: usando HTMX para além de TODO-Lists) e resolvi escrever esse texto para elucidar o contexto e os motivos que me levaram a decisão de usá-lo.

O que é o HTMX?

htmx gives you access to AJAX, CSS Transitions, WebSockets and Server Sent Events directly in HTML, using attributes, so you can build modern user interfaces with the simplicity and power of hypertext

Home do htmx.org

Resumidamente, o HTMX é uma biblioteca JavaScript que permite que você use transições, faça requisições e coisas do tipo utilizando atributos HTML para construir interfaces modernas utilizando HTML (principalmente em servidores que renderizam HTML, como é o caso do Django).

Contexto e Motivos pela escolha

1. Template Engine

O Django é, por padrão, um framework que implementa um sistema de templates que devolve HTML para o navegador. Junto com o sistema de templates, existe um sistema de gerenciamento de arquivos estáticos.

Esse primeiro contexto é importante aqui pois ao utilizar a stack Django + HTMX, não é necessário implementar, adaptar ou configurar nenhum sistema de templates.

2. Django-Admin

O Django-Admin é uma aplicação (ou um módulo, por assim chamar), incluída junto a distribuição django e que fornece uma interface de administração fácil de ser utilizada para gerenciar os models criados dentro dos projetos.

A partir do item anterior, já é possível imaginar que o Django-Admin usa, fundamentalmente, templates HTML e renderização server-side (que devolve o HTML).

Em alguns casos, quando há a necessidade de alguma funcionalidade com maior dinamização dentro do django-admin é mais factível e rápido usar uma biblioteca que faça a ponte para o mesmo sistema de templates HTML que utilizar um framework ou biblioteca front-end, como o React.

3. Autenticação e Permissão

Assim como o conjunto de utilitários para o painel administrativo, o django traz por padrão um sistema de autenticação e permissões configurável e utilizar o HTMX remove a necessidade de inserir outros tipos de autenticação (como JWT amplamente usada para API's).

Outro ponto relevante sobre a autenticação e permissão é que ao utilizar o Django-Admin e uma aplicação Django padrão server-side, a autenticação entre ambiente de admin e aplicação é compartilhada de forma simples, já que, na prática, é o mesmo site.

4. Funcionalidades do Django

O Django possui facilitadores como sistema de formulários e widgets que se integram muito bem com a Template Engine e facilitam coisas como validar os dados e, consequentemente, armazenar no banco de dados.

5. Escopo

Tudo o que descrevi acima foi bastante decisivo para a escolha do HTMX, mas, talvez, o que tenha sido mais decisivo foram os escopos das aplicações e funcionalidades onde o HTMX foi utilizado. São escopos onde os formulários são simples, não exigiam muitas manipulações ou validações. Não existem formulários com muita complexidade (por exemplo, um formulário de cadastro de cliente onde você pode adicionar vários dependentes no cadastro, etc.).

Mesmo que na maioria dos formulários complexos eu considere como falha de decisões, nem sempre essas decisões são dos devs.

Dados os motivos acima, ter conhecimento do framework de back-end / server-side ao qual se vai trabalhar, aliado ao HTMX, é importante para decidir se os requisitos dos formulários e outras necessidades podem, ou não, se tornar empecilhos.

Alguns contrapontos

Nem tudo são flores.

Em algumas situações é difícil fazer o que se quer fazer com a biblioteca, principalmente pela baixa quantidade, atualmente, de conteúdos.

Assim como em framework's front-end, como o react, lidar com redirecionamento de URL's pode ser bastante complexo, por exemplo pra preservar filtros em requisições via HTMX.

Existem algumas complexidades com que eu preciso lidar que eu, no atual momento, não transfiro essa responsabilidade ao HTMX e, portanto, não irei listá-las aqui.

Quer dizer, então, que agora eu só uso HTMX?

Bem, não. Por mais que eu tenha gostado bastante do desenvolvimento com o HTMX integrado ao Django, uso em poucos projetos e, na maioria das vezes, não é a única forma de dinamização das páginas (em alguns casos é preciso utilizar bastante JavaScript Vanilla ou outras bibliotecas como o React).

Além disso, algumas aplicações com as quais trabalho continuam sendo feitas com API's Rest usando JSON e front-end's como SPA's.

Tudo depende da análise dos pontos listados acima e de contextos das necessidades do negócio, se o projeto já está em andamento, se existe time, se é um projeto que farei sozinho como freelancer, dentre outras questões.

Django, Htmx e React: usando HTMX para além de TODO-Lists

Eduardo Oliveira — Tue, 09 Apr 2024 23:40:57 +0000

Já faz algum tempo que o HTMX, que me foi apresentado pelo @JeffQuesado, me pareceu uma ideia muito legal para se trabalhar junto com Django, principalmente o Django-Admin que já tem uma estrutura fortemente baseada em server-side.

Conteúdos

Conteúdos
Introdução
Contextualização da Plataforma Atual
Entendendo o Problema
Por que HTMX se já usávamos React?
Questões técnicas
- Comunicação entre HTMX e React
- Confirmação para execução de ações
- Como é que isso ai funciona?
E o futuro?

Introdução

Em uma demanda de um dos projetos em que atuo, precisávamos de uma funcionalidade para a qual o uso do HTMX se encaixaria perfeitamente e esse texto tem como objetivo levantar questões pelas quais foi decidido o uso do HTMX e não de outras ferramentas e elucidar como foram feitas integrações entre Django, HTMX e React para construir ferramentas reais.

O título é uma inspiração de um tweet que vi, alguns dias atrás, que questionava se alguém estava utilizando o HTMX para algo mais além de criar TODO-Lists.

Contextualização da Plataforma Atual

O back-end do projeto utiliza o Django com Django-Rest-Framework para servir uma API de integração para um app mobile e, para gerenciamento dos conteúdos, o Django-Admin é utilizado.

O django-admin possuí, nas páginas de formulário, uma estrutura parecida com a seguinte: um cabeçalho ocupado toda a largura da página, e logo a baixo uma sidebar e o conteúdo principal, que no caso é um formulário.

Em alguns formulários, a estrutura e arquitetura de informação dos models demandava um controle de carregamento e de exibição de itens complexo usando lazy-loading. Desse modo, quando o ferramental do django e do django-admin deixou de suprir as necessidades, parte desses formulários foi construída utilizando aplicações pequenas com React.

Essas aplicações React que eram carregadas apenas em páginas específicas não demandavam, por exemplo, o uso de routers e coisas do tipo.

Entendendo o Problema

O painel de administração é utilizado para algo próximo a um CMS (content management system) para um app de idiomas. Durante a criação de algumas "entidades" dentro da plataforma, seria necessário uma ferramenta, em popup, para consultar as "entidades" já cadastradas, pois esse processo atualmente era gerenciado com planilhas externas, aumentando a complexidade no uso do painel.

Essa mesma ferramenta deveria, também, fornecer a opção de clonar entidades para a página em que se estava trabalhando (alternado a entidade paí/chave estrangeira).

Por que HTMX se já usávamos React?

Quando começamos a avaliar a funcionalidade, a primeira discussão foi: será que o HTMX se encaixa bem aqui? ou será melhor lidar com React?

Um dos principais pontos levados em consideração: a estrutura do django e do django-admin já trazia uma quantidade enorme de código e funcionalidades que poderiam ser reutilizadas para a exibição, como paginação, etc. na aplicação react que roda nessa aplicação não lidava com paginação nem com diversas outras coisas que demandaria muito mais tempo para implementar que utilizando partes dos templates do django-admin adaptados.

Como essa funcionalidade não seria, sempre, inserida nas mesmas páginas que o formulário react, haveria muito trabalho pra conciliar o uso do react, bundlers, etc.

Esse conjunto de fatores foram os principais motivantes para a adoção do HTMX, que diferente do react que teriamos que lidar com bundler, só importamos o script onde fosse necessário utilizar as tags do HTMX.

A simplicidade que o HTMX trouxe para essa implementação, talvez tivesse sido utilizada no lugar do react se a conhecêssemos na época.

Questões técnicas

Algumas questões que foram foco dos esforços no trabalho com essa funcionalidade serão tratadas nessa seção. Essas questões não foram, necessariamente, complexas ou problemáticas. São apenas pontos aos quais gostaria de comentar.

Comunicação entre HTMX e React

Como comentado, em algum lugar no texto acima, era necessário clonar itens para o formulário atual. Formulário esse, construído em React. Assim, ao integrar uma ação para clonar o item, utilizando o hx-post, é necessário que algum trigger seja disparado para que alguma parte da app React possa processar.

Um detalhe, ao qual não vou adentrar aqui, é que esses "links" para ações estão dentro de um formulário, então na chamada para o hx-post todos os campos do formulário também são enviados.

<span
  hx-post="/admin/my-action"
  hx-trigger="confirmed"
  hx-indicator=".htmx-indicator"
  title="Clonar"
>
  ...
</span>

O hx-trigger="confirmed" se deve a seção abaixo, onde tratamos sobre a confirmação para a execução da ação. Fora isso, no lado do servidor, utilizando django-htmx podemos inserir uma header HX-Trigger para disparar um trigger quando a ação do HTMX for finalizada:

def my_view(request):
    ...
    response = render(request, 'my_template.html', my_context)
    resp.headers['HX-Trigger'] = 'completeClone'
    return resp

Dentro do cliente react podemos adicionar o evento ao document devido ao event bubbling:

useEffect(() => {
  const fetch = async () => {
    ...
  }

  document.addEventListener('completeClone', fetch);
  return () => {
    document.removeEventListener('completeClone', fetch);
  }
}, []);

Confirmação para execução de ações

Para exibir confirmações de execução das ações, utilizamos a biblioteca SweetAlert2, que já estava no projeto pra ser utilizada em alguns outros momentos:

function confirmClone(element, title) {
  text = 'Deseja clonar o item <strong>"' + title + '"</strong>? Essa ação não poderá ser desfeita!'
  Swal
    .fire({
      title: 'Tem certeza?',
      html: text,
      showCancelButton: true,
      confirmButtonText: 'Sim, Clonar',
      cancelButtonText: 'Cancelar',
    })
    .then(function(result){
      if(!result.isConfirmed){
        return;
      }
      htmx.trigger(element, 'confirmed');
    });
}

A linha htmx.trigger(element, 'confirmed'); dispara o trigger que está no hx-trigger="confirmed" do span. Aqui é preciso completar, também, a tag:

<span
  hx-post="/admin/my-action"
  hx-trigger="confirmed"
  hx-indicator=".htmx-indicator"
  onclick="confirmClone(this, 'título do item!!!!')"
  title="Clonar"
>
  ...
</span>

Como é que isso ai funciona?

A implementação com HTMX fluiu muito bem, mas em diversos momentos foi necessária muita experimentação por falta de clareza do que, exatamente, os comandos fazem ou como lidar para que eles fizessem exatamente o que queria.

Mas, esse pode ser uma skill issue do prazo e de ser a primeira vez utilizando a documentação, tanto que as duas seções acima foram fortemente baseadas pelos seus exemplos (mas não pela sua documentação).

E o futuro?

Bom, desenvolver uma funcionalidade real com HTMX foi uma experiência muito boa e creio que o projeto tem muito potêncial, apesar que em diversos momentos, a depender da estrutura e do tamanho do projeto, eu continue achando que uma API (Rest ou intent based) com um cliente front-end ainda seja mais simples de se manipular.

Ainda assim, espero ter mais chances de usar o HTMX integrado ao django-admin que é, fundamentalmente, server-side.

Sua aplicação é um labirinto? Usabilidade e URL's

Eduardo Oliveira — Thu, 15 Feb 2024 11:06:33 +0000

De tempos em tempos, aparecem pessoas comentando sobre a possibilidade do uso de query strings (referência) para armazenar estados ao invés de usar estados "invisíveis" e não rastreáveis (mais adiante você entenderá o que eu quero dizer com não rastreáveis) como se fosse algo super inovador.

A verdade é que estamos voltando às origens.

Introdução
Estados Invisíveis
- O problema
- As soluções
Infinite Loading
Navegação em Abas
- Contraponto: O Contexto que importa
Filtros de busca
- Atualizando a listagem filtro por filtro
- Selecionando todos os filtros e aplicando
Modais e Caixas de Diálogos
Dicas de como melhorar esses pontos da usabilidade
- Estude sobre UX
- Benchmarking
- Pense como um usuário
Referências
Produtos Mostrados no Texto

Introdução

Esse texto tem como objetivo mostrar, de forma conceitual, casos de uso em que esse padrão é bastante utilizado e que, ao longo do tempo, começou a ser negligenciado, principalmente em SPA's (Single Page Applications).

Não será objetivo, aqui, explicar como devem ser feitas as implementações desses comportamentos em frameworks ou bibliotecas. Ainda assim, quando possível, citações e links de referências para documentações serão adicionados.

Partes do texto serão ilustradas com imagens e GIF's de aplicações, reais, em produção. O objetivo não é críticar o trabalho dos seus desenvolvedores.

É importante dizer, também, que algumas dessas animações, em GIF's, podem demorar a carregar, porém esse é um "manual" ilustrado que não seria a mesma coisa sem elas.

Estados Invisíveis

O primeiro tema que iremos discutir são os estados invisíveis e não rastreáveis (esse nome é, de fato, ruim e não sei o motivo pelo qual decidi usar, mas quando falo de rastreabilidade é, basicamente, a rastreabilidade quanto ao histórico do navegador e nos próximos tópicos você entenderá isso).

O problema

Durante o processo de criação de aplicações front-end é comum que sejam utilizados estados (useState no React ou variáveis ou propriedades das classes no Angular) para gerenciar o estado de componentes que lidam com fluxo de dados, como por exemplo filtros e paginação.

Isso resolve o problema: lida com o gerenciamento de estado do fluxo de dados desses componentes. Porém, isso também introduz um novo problema: esses estados são invisíveis e não registram histórico no navegador.

Por exemplo, imagine que tenhamos uma página de estoque, com uma lista de produtos, paginados. Ao entrar nessa página, clicamos para abrir a página 2 e, então, clicamos em voltar, no navegador, voltamos pra página inicial. Veja o GIF abaixo:

Isso é uma falha na usabilidade do produto, que atinge, inclusive, páginas famosas. Vejam, por exemplo, a página Todos os Cursos do Eu Capacito:

Percebam que um fator em comum nesses exemplos é que ao clicarmos em algum número de página a URL não é alterada.

As soluções

Existem, pelo menos, duas soluções ideais para esse problema. Ambas passam pelo uso da URL como estado da página.

Query String

A primeira solução é utilizar a query string para determinar estados. Por exemplo: podemos acrescentar ?page=2 ou ?p=2 na URL para indicar a página e a aplicação consegue lidar com esse parâmetro para determinar qual a página que deve ser exibida.

Um exemplo de produto bastante conhecido, que utiliza query strings para paginar os dados é o GitHub Issues:

Essa solução pode ser implementada em diversos frameworks, como, por exemplo, em Angular e em React com react-router-dom.

Pathname

Outra forma de solucionar esse problema é utilizar o pathname para armazenar esses estados. Por exemplo, imagine as seguintes rotas: categoria/marketing/ e categoria/marketing/page/2/. É claramente perceptível que a primeira rota indica a página 1 e que a segunda rota indica a página 2.

Esse exemplo foi retirado do blog RockContent.

Infinite Loading

Existe um outro método de paginação de dados que é o infinite loading que carrega e agrega novos itens a parte de baixo a medida que é necessário (seja pelo scroll, seja por um botão de carregar mais). Esse tipo de solução é bastante utilizado quando o conteúdo não tem o próposito de ser bem estruturado (ter começo, meio e fim, por assim dizer). Complicado? vamos explicar com mais calma:

Imagine que você entra na home-page de um site de notícias: você faz isso pra descrobrir as notícias mais recentes e não quer saber quantas páginas de notícia existem.

Você quer rolar a tela até chegar numa data, ou numa notícia que já viu, e ai saberá que o que vem abaixo não lhe interessa mais.

Agora, por outro lado, para que você entenda que certo e errado depende do contexto, imagine que o usuário, vendedor em um marketplace, queira analisar todas as vendas que fez, então ele começa a rolar a página, mais itens são carregados, continua rolando, mais itens são carregados, mas perceba que ele não sabe nem quantos itens ainda faltam pra serem carregados e, o pior ainda, se ele apertar no botão de voltar, como em praticamente todo sistema que usa essa estratégia, ele voltará para a página anterior, e não para a última parcela das compras que foi carregada, pois não há marcação de paginação na URL.

Um exemplo disso pode ser visto no feed do Twitter ou do LinkedIn, percebam que a ideia do feed é a descoberta de novos itens, logo, sem estrutura de começo, meio e fim.

Navegação em Abas

Outro lugar onde esse é um problema de usabilidade claro são no uso das abas, veja o seguinte comportamento:

Perceba que, após alterar a aba, que é o conteúdo principal da página, e clicar em voltar, no navegador, voltamos a página inicial e não a aba anterior. Em alguns casos, mesmo que haja o mapeamento para as URL's, o comportamento não é padrão no browser, veja o comportamento na seguinte página (observe a URL e o comportamento do clique no botão de voltar):

Veja um caso de uso onde o mapeamento em URL e o comportamento do navegador funcionam de forma satisfatória:

Contraponto: O Contexto que importa

O contexto é o que mais importa. Manter a aba ativa mapeada na URL é uma tática muito legal quando o conteúdo principal é o componente de abas. Agora, imagine que o componente de abas aparece no meio de uma página, entre diversos outros conteúdos: guardar essa aba ativa na URL não faz a menor diferença. Veja o caso da loja da Steam:

Nesse caso, vale a mesma lógica que comentamos sobre o uso de abas para descoberta de conteúdo no Infinite Loading.

Filtros de busca

Comentamos muito sobre paginação, navegação em abas, mas o mesmo se aplica para filtros. Como exemplo, podemos olhar a página de produtos, em quase todos os e-commerce com as filtragens: geralmente todas são mapeadas na query string da URL.

Ao mapear os filtros é importante levar em consideração o comportamento dos filtros com relação a filtragem:

sempre quando o usuário alterar um filtro, a listagem já se atualiza com os novos dados;
o usuário altera todos os campos e depois clica em aplicar os filtros.

Algumas das características desses dois comportamentos serão discutidos agora.

Atualizando a listagem filtro por filtro

Observe que a filtragem de um e-commerce, como por exemplo o site da Hering, geralmente se aparenta com categorias:

Nesse caso, geralmente, usam-se o comportamento de a cada item selecionado a listagem já é atualizada. Percebam, também, que, por conta da categorização dos filtros, o histórico é preservado:

Clicamos em Feminino -> Alfaiataria -> Alongado. Após esse fluxo, clicamos em voltar no navegador e voltamos para somente Alfaiataria. Clicamos novamente em voltar e ficamos somente na página de Feminino.

É visível que, a depender da quantidade de filtros e da forma como se pretenda usar esses filtros, essa pode não ser a melhor escolha.

Selecionando todos os filtros e aplicando

Esse comportamento é, geralmente, mais utilizado quando os filtros possuem uma aparência de filtragem e não de categoria.

Por exemplo, quando os filtros incluem datas de início e de fim, tem-se o seguinte caso de uso: altera-se a data de início pra depois da data de fim. A nova data de início e a data de fim que já estava preenchida não faz sentido.

Um exemplo disso é a tela de extrato da NuInvest:

Outro exemplo de uso, bastante comum, para esse tipo de comportamento é quando a API que devolve a listagem é pesada, mal desenhada, não otimizada, etc. e demora muito pra carregar os dados.

Modais e Caixas de Diálogos

Modais e caixas de diálogos são muito bons em diversas situações, mas as vezes esquecemos um detalhe muito importante sobre eles: eles são, basicamente, uma nova página dentro da nossa própria página.

Desse modo, perceba o seguinte comportamento ao tentar escrever uma publicação no LinkedIn e resolver voltar:

Um dos passos percorridos pelo usuário para chegar ao modal foi perdido ao clicar em voltar.

Para evitar esse tipo de problema, o estado dos modais também devem ser mapeados na URL, de alguma forma. Existem diversas formas de se implementar isso e um exemplo, não convencional, é o Trello que usa o id do card na barra de endereços:

Dicas de como melhorar esses pontos da usabilidade

Existem algumas formas de melhorar a usabilidade de aplicações quanto ao mapeamento de URL's. Nas seções abaixo iremos falar sobre algumas dicas de como melhorar isso.

Estude sobre UX

Ler sobre UX é uma boa forma de aprender o comportamento de determinadas interfaces. Isso é interessante mas não resolve, de todo, o problema. Vide o texto UX: Modais, quando (e quando não) usá-los, texto oriundo da Nielsen Norman Group, que não cita o uso das URL's.

Benchmarking

Faça benchmarking em produtos que usa no seu dia a dia. Entre, investigue o comportamento, clique em voltar, clique em avançar, feche o modal clicando no ícone de fechar e clique em voltar. Selecione os filtros, clique em voltar, avançar, mude os filtros um a um, tente mudar a data pra datas inválidas (a data de início posterior a data de fim, por exemplo).

Entenda como os componentes reagem a todos esses casos.

Pense como um usuário

Além de fazer benchmarking, pense como o seu usuário final. O que você achou do comportamento que você encontrou nos teus benchmarkings?

Referências

Produtos Mostrados no Texto

Foto de Aron Visuals na Unsplash

Lidando com regressão visual: enfrentando desafios com Django, Selenium e Pillow

Eduardo Oliveira — Mon, 11 Sep 2023 01:15:58 +0000

O django-image-uploader-widget é um projeto de componente de upload de imagem para o django. Por motivos de retrocompatibilidade entre as versões 3.x e 4.x do django, foi decidido implementar testes de regressão visual utilizando Selenium e Pillow. Nesse texto vamos trabalhar esse tema e seus desafios.

Índice

Introdução
O suporte do django a suas versões
O que é um teste de regressão visual?
O Browser e o Selenium
Pillow
Juntando as Peças
Desafios
- O problema inicial
- Alteração nas fontes
- Animações, transições e threshold
- Theme Toggle
Referências

Introdução

O django-image-uploader-widget é um projeto de componente de upload de imagem para o django, criado para melhorar a estética dos uploaders originais. É mantido como open-source desde o início, inclusive recebendo colaborações de outros desenvolvedores.

Com o lançamento das versões 4.x do django, o componente passou a ter diferenças significativas no visual entre algumas de suas versões, conforme registrado na issue #96.

A partir dessa diferença visual, em diferentes versões do django, entra no radar do projeto a possibilidade de implementação de testes de regressão visual. Nesse artigo vamos explorar os desafios enfrentados durante essa implementação.

O suporte do django a suas versões

Um ponto que vale ser levado em consideração, para justificar a decisão de implementar testes de regressão visual, é o fato de que o django mantem, por muito tempo, suporte a diversas de suas versões (Ver Referência), como na imagem:

O que é um teste de regressão visual?

Como o Guilherme Ananias comenta no seu texto (Ver Referência), um teste de regressão visual é um tipo de teste que irá garantir que qualquer alteração no código não irá alterar a forma como o usuário final irá verá esse componente ou página.

Dado o contexto de suporte a múltiplas versões do django e, principalmente, do django-admin, com alterações de estilização entre as versões, esse tipo de teste pode, também, ser utilizado para garantir retrocompatibilidade entre o componente e as versões do django.

O Browser e o Selenium

O código desse componente já possuía uma suite de testes, funcionais, rodando com o Selenium e o Chrome Driver. A justificativa para o uso de testes funcionais pode ser lida nas documentações do projeto.

Tendo o browser e, mais especificamente, o selenium disponíveis, é possível utilizar o método screenshot(filename) para salvar um screenshot de um elemento da página, conforme documentação.

Pillow

A utilização dos campos de imagem do django só é possível com a biblioteca Pillow instalada no projeto. Essa biblioteca traz, com a sua instalação, métodos para lidar com a diferença entre imagens (Ver Referência).

Juntando as Peças

Ao utilizar o selenium e a lib Pillow é possível, de forma bem simples, tirar screenshot dos elementos e comparar com outro screenshot já armazenado (ver implementação).

Desafios

Foram enfrentados diversos desafios durante a implementação dos testes de regressão visual. Alguns desses desafios foram causados pela natureza das escolhas para a implementação desses testes e outros pela natureza do django e django-admin.

O problema inicial

Toda a implementação dos testes de regressão visual nasceram devido a um problema entre versões do django, vide #96, onde, devido a alteração de estilos do django-admin, adicionando flexbox, causou a quebra da estilização.

Assim, é necessário dizer que um dos primeiros desafios é da natureza do django e, principalmente, do suporte a múltiplas versões do mesmo.

A solução, pra esse caso, em específico, foi simples e corriqueira fazendo o tratamento tanto pro css das versões 3.x do django-admin quanto para as novas, que utilizam flexbox.

Alteração nas fontes

Complementando o problema inicial, logo nos primeiros testes, foi identificado uma alteração no padrão visual do componente (ou widget), em uma das versões mais recentes do django. As fontes do widget estavam diferentes. Ao buscar pelas releases notes do django, é observado a seguinte descrição (referência):

The admin’s font stack now prefers system UI fonts and no longer requires downloading fonts. Additionally, CSS variables are available to more easily override the default font families.

Uma solução, não necessariamente a melhor, porém a mais simples foi a de adiantar essa alteração das fontes, para o componente de upload de imagens, independente da versão do django.

Animações, transições e threshold

Da natureza da comparação das imagens, junto ao fato de ser uma aplicação web executando, tem-se o problema de ter alguns pixeis de diferença em algumas situações, provavelmente causado por animações e transições.

Para aguardar o fim das transições e animações, o método time.sleep() do Python foi utilizado. Por conta da utilização do time.sleep() é, natural, que o tempo de execução dos testes aumente significativamente.

Nesse ponto, é sempre importante deixar pontuado que, não existe certo ou errado, ou solução pra todos os problemas, ou, ainda, solução sem contrapontos. Toda técnica, ou escolha, geralmente, tem suas vantagens e desvantagens. Cabe ponderar se as vantagens superam as desvantagens no contexto ao qual se quer utilizar a ferramenta.

Por fim, após a implementação do time.sleep() raras se tornaram as vezes que as imagens divergiam em locais que não deveriam, porém, por garantia, ainda foi implementado um sistema de comparação com threshold (limiar) para esses casos.

Theme Toggle

Ainda nas release notes da versão 4.2 do django é possível verificar a adição de um theme toggle no admin. Quando o componente foi, inicialmente, desenvolvido, as versões 4.x do django ainda não tinham assumido o status de LTS. Além disso, por um tempo, apenas as manutenções básicas foram dadas ao projeto. Dados esses contextos, o componente não tinha suporte a mudança de tema pela interface de usuário.

Esse problema só foi percebido, de fato, com a implementação dos testes de regressão visual e, para a solução, foi aberta uma nova issue no GitHub (#103).

Esse foi o único caso em que foi implementada uma condicional da versão do django em que os testes estavam sendo executados:

import django
# ...

class InlineEditorUIRegressionTestCase(IUWTestCase):
    # ...
    def test_ui_initialized_toggle_dark_theme_inverted(self):
        self.dark_mode()

        major, minor, _, _, _ = django.VERSION
        if major < 4 or minor < 2:
            return

Referências

As referências citadas no texto, listadas:

Foto de Budka Damdinsuren na Unsplash

Full-Text Search: Criando um Back-End de Filtro para o Django Rest-Framework

Eduardo Oliveira — Sat, 22 Apr 2023 13:43:53 +0000

O texto Full-Text Search: Implementando com Postgres e Django [1] comenta sobre a implementação do sistema de Full-Text Search do Postgres, trazido pelo Leandro Proença no texto A powerful full-text search in PostgreSQL in less than 20 lines [2], utilizando o django.

O projeto está no GitHub [3] e, para complementá-lo, esse texto tem por objetivo, construir um back-end de filtro, i.e. um adapter de filtro, para lidar com o full-text search, como no algoritmo do texto anterior dentro do rest-framework.

Pra poder adicionar esse suporte, da melhor forma possível, podemos criar um filter back-end customizado. São utilizados, como referência, o SearchFilter original do django [4] e [5].

Mostre-me o código

O código desenvolvido nesse texto está disponível no repositório django-full-text-search no Github.

Disclaimer:

O código da versão desse texto está disponível na branch texto-2.

Implementando o BaseFilterBackend

Para criar o back-end de filtro, é preciso implementar a classe rest_framework.filters.BaseFilterBackend:

from rest_framework.filters import BaseFilterBackend

class FullTextSearchFilter(BaseFilterBackend):
    pass

Obtendo os parâmetros

Os primeiros métodos que serão implementados na classe acima são apenas métodos que buscam atributos na requisição, como o parâmetro ?search, ou no ModelViewSet como, por exemplo, o search_fields. Esse código é bem parecido com o da referência em [5]:

from rest_framework.filters import BaseFilterBackend
from rest_framework.settings import api_settings

class FullTextSearchFilter(BaseFilterBackend):
    search_param = api_settings.SEARCH_PARAM

    def get_config(self, view, request):
        return getattr(view, "search_config", None)

    def get_search_fields(self, view, request):
        return getattr(view, "search_fields", None)

    def get_similarity_threshold(self, view, request):
        return getattr(view, "similarity_threshold", 0)

    def get_search_term(self, request):
        params = request.query_params.get(self.search_param, '')
        params = params.replace('\x00', '')  # strip null characters
        params = params.replace(',', ' ')
        return params

Fazendo a Busca

O método mais importante dessa classe é, sem dúvidas, o filter_queryset que é o método que faz as alterações em um queryset para devolver a resposta da API.

É preciso, antes de tudo, obter os parâmetros para fazer nossa busca, por meio dos métodos implementados acima:

def filter_queryset(self, request, queryset, view):
    search_fields = self.get_search_fields(view, request)
    search_term = self.get_search_term(request)
    config = self.get_config(view, request)
    threshold = self.get_similarity_threshold(view, request)

Um primeiro ponto, que deve ser levado em consideração, é que, caso a variável search_fields ou a search_term não esteja preenchida, podemos retornar o queryset sem fazer alteração:

def filter_queryset(self, request, queryset, view):
    # ...

    if not search_term or not search_fields:
        return queryset

O restante do método é bem parecido com o que já implementamos no texto anterior:

def filter_queryset(self, request, queryset, view):
    # ...

    search_vector = SearchVector(*search_fields, config=config)
    search_query = SearchQuery(search_term, config=config)

    queryset = queryset.annotate(
        search=search_vector,
        rank=SearchRank(
            search_vector,
            search_query,
        ),
        similarity=TrigramSimilarity(*search_fields, search_term),
    ).filter(
        Q(search=search_query) | Q(similarity__gt=threshold)
    ).order_by("-rank", "-similarity")

    return queryset

Faz-se importante denotar que o search_fields aqui é usado como *search_fields para "desconstruir" o array. Assim, se search_fields = ["name", "description"], a criação da instância SearchVector seria feita como SearchVector("name", "description", config=config).

Por fim, a classe, completa, será:

class FullTextSearchFilter(BaseFilterBackend):
    search_param = api_settings.SEARCH_PARAM

    def get_config(self, view, request):
        return getattr(view, "search_config", None)

    def get_search_fields(self, view, request):
        return getattr(view, "search_fields", None)

    def get_similarity_threshold(self, view, request):
        return getattr(view, "similarity_threshold", 0)

    def get_search_term(self, request):
        params = request.query_params.get(self.search_param, '')
        params = params.replace('\x00', '')  # strip null characters
        params = params.replace(',', ' ')
        return params

    def filter_queryset(self, request, queryset, view):
        search_fields = self.get_search_fields(view, request)
        search_term = self.get_search_term(request)
        config = self.get_config(view, request)
        threshold = self.get_similarity_threshold(view, request)

        if not search_term or not search_fields:
            return queryset

        search_vector = SearchVector(*search_fields, config=config)
        search_query = SearchQuery(search_term, config=config)

        queryset = queryset.annotate(
            search=search_vector,
            rank=SearchRank(
                search_vector,
                search_query,
            ),
            similarity=TrigramSimilarity(*search_fields, search_term),
        ).filter(
            Q(search=search_query) | Q(similarity__gt=threshold)
        ).order_by("-rank", "-similarity")

        return queryset

Usando o FullTextSearchFilter

A classe FullTextSearchFilter pode ser utilizada nos filter_backends dos ModelViewSet do django-rest-framework. Simplificando:

from rest_framework import serializers
from rest_framework.viewsets import ModelViewSet
from texto.models import Singer
from core.filters import FullTextSearchFilter

class SingerSerializer(serializers.ModelSerializer):
    class Meta:
        model = Singer
        fields = "__all__"

class SingerViewSet(ModelViewSet):
    queryset = Singer.objects.all()
    serializer_class = SingerSerializer
    filter_backends = [FullTextSearchFilter]
    search_config = "portuguese"
    search_fields = ["name"]

Ao registrar o SingerViewSet nas urls do projeto já é possível fazer chamadas para o endpoint utilizando o ?search como full-text search:

from django.urls import path, include
from rest_framework.routers import SimpleRouter
from .viewsets import SingerViewSet

router = SimpleRouter()
router.register("singer", SingerViewSet, "Singer")

urlpatterns = [
    path('api/', include(router.urls))
]

Mostrando o Rank e Similarity no retorno da API

É possível, inclusive, exibir os dados de rank e similarity no retorno da API. Como esses dados estão sendo anotados, i.e. acrescentados, na entidade, é possível, apenas, alterar o ModelSerializer:

class SingerSerializer(serializers.ModelSerializer):
    rank = serializers.FloatField(read_only=True)
    similarity = serializers.FloatField(read_only=True)

    class Meta:
        model = Singer
        fields = "__all__"

Mas, e sem a busca?

Acrescentar, apenas, o rank e similarity no ModelSerializer traz um problema: quando o endpoint é chamado sem o ?search os dados de rank e similarity não são retornados:

Isso pode ser resolvido, acrescentando, no construtor do FloatField, o parâmetro default=0:

class SingerSerializer(serializers.ModelSerializer):
    rank = serializers.FloatField(read_only=True, default=0)
    similarity = serializers.FloatField(read_only=True, default=0)

    class Meta:
        model = Singer
        fields = "__all__"

Filtrando por Similaridade

Por fim, para filtrar por similaridade, é possível definir a variável similarity_threshold no ModelViewSet:

class SingerViewSet(ModelViewSet):
    queryset = Singer.objects.all()
    serializer_class = SingerSerializer
    filter_backends = [FullTextSearchFilter]
    search_config = "portuguese"
    search_fields = ["name"]
    similarity_threshold = 0.3

Referências

[1] Full-Text Search: Implementando com Postgres e Django

[2] A powerful full-text search in PostgreSQL in less than 20 lines

[3] django-full-text-search

[4] Filtering - SearchFilter

[5] rest_framework/filters.py

Foto de Capa por Douglas Lopes no Unsplash

Full-Text Search: Implementando com Postgres e Django

Eduardo Oliveira — Mon, 10 Apr 2023 11:29:58 +0000

Algum tempo atrás vi o texto "A powerful full-text search in PostgreSQL in less than 20 lines" do Leandro Proença [1] e quis implementar algo assim pra projetos que não demandam o poder de um Apache Lucene ou de um Elastic Search.

O django já possui, em seu core, uma aplicação com métodos que são utilizados apenas com o Postgres e, para a minha surpresa, todos os conceitos de full-text search já estavam disponíveis nesse app.

Restou, nesse caso, tentar reproduzir, por assim dizer, a query do texto original utilizando o ORM do django e os métodos do full-text search.

Esse texto tem, por objetivo, trazer explicações sobre como essa implementação foi feita. Fundamentalmente, esse texto será uma versão explicada dessa thread no twitter.

Mostre-me o código

Todo o código-fonte do projeto está disponível no GitHub, nesse repositório.

Disclaimer:

O código da versão desse texto está disponível na branch texto-1.

Adicionando configurações necessárias

Dentro do settings.py do projeto, precisamos adicionar a aplicação django.contrib.postgres dentro da variável de INSTALLED_APPS para que possamos utilizar as ferramentas do django próprias para o Postgres:

# ...

INSTALLED_APPS = [
    'django.contrib.admin',
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.messages',
    'django.contrib.staticfiles',
    'django.contrib.postgres',
]

# ...

Criando o model

Precisamos criar um model para poder utilizar os conceitos da busca dentro dele. Para simplificar, esse caso, utilizamos um model com um único campo de texto para as buscas:

class Singer(models.Model):
    name = models.CharField("Cantor", max_length=150)

    def __str__(self):
        return self.name

    class Meta:
        verbose_name = "Cantor"
        verbose_name_plural = "Cantores"

Criando uma view

Para testar os conceitos de full-text search, podemos criar uma view. Antes, é necessário dizer que nesse texto estou usando views padrão do django com templates em HTML para não adicionar mais complexidade lidando com o Rest Framework.

Podemos criar uma view que recebe uma query string para fazer a busca:

from django.shortcuts import render
from .models import Singer

def search_singer(request):
    term = request.GET.get('q')
    if term:
        # TODO: fazer busca aqui
    else:
        singers = Singer.objects.order_by("-id").all()

    context = {
        'singers': singers,
        'term': term,
    }
    return render(request, "cantor.html", context)

O template cantor.html que estou utilizando é bem simples apenas para permitir testes de forma mais fácil:

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta http-equiv="X-UA-Compatible" content="IE=edge">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Buscando Cantores</title>
</head>
<body>

    <div>

        <form action="">
            <input type="search" name="q" {% if term %} value="{{ term }}" {% endif %} />
            <button type="submit">Pesquisar</button>
        </form>

    </div>

    {% if singers %}
        <main>
            {% for item in singers %}
                <div>
                    <h3>{{item.name}}</h3>
                    {% if item.rank or item.similarity %}
                        <div>
                            Rank: {{item.rank}}, Similaridade: {{item.similarity}}
                        </div>
                    {% endif %}
                </div>
            {% endfor %}
        </main>
    {% endif %}

</body>
</html>

Full-Text Search

Precisamos, primeiro, criar um SearchVector (ts_vector) e um SearchQuery (tsquery). Assim:

from django.contrib.postgres.search import SearchVector, SearchQuery

# ...

vector = SearchVector("name", config="portuguese")
query = SearchQuery(term, config="portuguese")

# ...

O vector é feito assim pra utilizar a coluna "name" do model Singer. A query é feita para processar a variável term recebida no código da view acima.

O próximo ponto é criar annotations para fazer o select de campos como o to_tsvector e o ts_rank (o método .annotate do Django ORM faz o select de outros campos e agrega eles a entidade):

from django.contrib.postgres.search import SearchVector, SearchQuery, SearchRank

# ...

vector = SearchVector("name", config="portuguese")
query = SearchQuery(term, config="portuguese")
singers = Singer.objects.annotate(
    search=vector,
    rank=SearchRank(vector, query),
).filter(
    search=query
).order_by("-rank").all()

# ...

Adicionando o código dentro da view, passamos a ter:

from django.shortcuts import render
from django.contrib.postgres.search import SearchVector, SearchQuery, SearchRank
from .models import Singer

def search_singer(request):
    term = request.GET.get('q')
    if term:
        vector = SearchVector("name", config="portuguese")
        query = SearchQuery(term, config="portuguese")
        singers = Singer.objects.annotate(
            search=vector,
            rank=SearchRank(vector, query),
        ).filter(
            search=query
        ).order_by("-rank").all()
    else:
        singers = Singer.objects.order_by("-id").all()

    context = {
        'singers': singers,
        'term': term,
    }
    return render(request, "cantor.html", context)

Utilizando um pequeno grupo de dados para teste:

Podeos testar e verificar que passamos a ter uma busca funcional:

Porém, ainda temos alguns problemas, pois, por exemplo, na busca por palavras incompletas, perdemos o ranqueamento:

Nesse ponto, entra a busca por similaridade que, combinada com o Full-Text Search nos permitirá fazer uma busca mais funcional.

Busca por Similaridade

Precisamos, primeiro, adicionar a extensão pg_trgm no banco de dados. Podemos fazer isso manualmente ou podemos criar uma migration vazia e adicionar essa extensão na migration. Vou seguir pela segunda opção. Para a primeira, basta executar o comando no banco de dados:

CREATE EXTENSION pg_trgm

Para a segunda abordagem, podemos executar o comando python manage.py makemigrations nome_do_app --empty e ele criará uma -migration vazia. A partir da migration vazia, podemos adicionar o import ao CreateExtension e adicionar dentro de operations:

from django.db import migrations
from django.contrib.postgres.operations import CreateExtension


class Migration(migrations.Migration):
    dependencies = [
        ('texto', '0003_alter_feat_music'),
    ]

    operations = [
        CreateExtension("pg_trgm")
    ]

Basta agora executar python manage.py migrate e teremos a extensão criada no banco de dados.

Agora, dentro da nossa busca, podemos fazer o uso do TrigramSimilarity para melhorar nossos resultados. Primeiro, vamos adicionar dentro do .annotate:

from django.contrib.postgres.search import SearchVector, SearchQuery, SearchRank, TrigramSimilarity

# ...

singers = Singer.objects.annotate(
    search=vector,
    rank=SearchRank(vector, query),
    similarity=TrigramSimilarity("name", term),
)

# ...

Precisamos, também, alterar o .filter para utilizar de um operador lógico OU. Para isso, precisamos fazer uso do Q(condição 1) | Q(condição 2) do django:

from django.contrib.postgres.search import SearchVector, SearchQuery, SearchRank, TrigramSimilarity
from django.db.models import Q

# ...

singers = Singer.objects.annotate(
    search=vector,
    rank=SearchRank(vector, query),
    similarity=TrigramSimilarity("name", term),
).filter(
    Q(search=query) | Q(similarity__gt=0)
).order_by("-rank", "-similarity").all()

# ...

Aqui, o que fazemos é adicionar o campo de similarity na nossa query e filtrar pra "o full-text search encontrou" ou "a similaridade é maior que zero". A partir desse momento, fazendo a mesma busca de um dos prints acima:

Por fim, nossa view passa a ter o código:

from django.shortcuts import render
from django.db.models import Q
from django.contrib.postgres.search import (
    SearchQuery,
    SearchRank,
    SearchVector,
    TrigramSimilarity,
)
from .models import Singer

def search_singer(request):
    term = request.GET.get('q')
    if term:
        vector = SearchVector("name", config="portuguese")
        query = SearchQuery(term, config="portuguese")
        singers = Singer.objects.annotate(
            search=vector,
            rank=SearchRank(vector, query),
            similarity=TrigramSimilarity("name", term),
        ).filter(
            Q(search=query) | Q(similarity__gt=0)
        ).order_by("-rank", "-similarity").all()
    else:
        singers = Singer.objects.order_by("-id").all()

    context = {
        'singers': singers,
        'term': term,
    }
    return render(request, "cantor.html", context)

É possível utilizar tanto o rank ou o similarity para cortar valores, conforme exemplos da documentação.

Por último, podemos adicionar um índice dentro do nosso model para lidar com performance das queries:

from django.db import models
from django.contrib.postgres.indexes import GinIndex
from django.contrib.postgres.search import SearchVector

class Singer(models.Model):
    name = models.CharField("Cantor", max_length=150)

    def __str__(self):
        return self.name

    class Meta:
        verbose_name = "Cantor"
        verbose_name_plural = "Cantores"
        indexes = [
            GinIndex(
                SearchVector("name", config="portuguese"),
                name="singer_search_vector_idx",
            )
        ]

Todo o código-fonte do projeto está disponível no GitHub, nesse repositório.

Disclaimer:

O código da versão desse texto está disponível na branch texto-1.

Referências

1 - A powerful full-text search in PostgreSQL in less than 20 lines

2 - Full text search - Django Documentation

Foto de capa por Mick Haupt no Unsplash.

How to Hide Features from Production Environment in React

Eduardo Oliveira — Fri, 31 Mar 2023 23:09:16 +0000

I writed, in brazilian portuguese, at Inventare, an article about testing into production with feature flag. Currently, we have an old project writed in React (create-react-app) with two environments, test (validation) and production and, in some cases, we need to hide some things from the production environment.

The project use env-cmd package to run the react scripts with different .env files to get the projects :

{
  ...
  "scripts" {
    "start": "env-cmd -f ./.env react-scripts start",
    "build": "env-cmd -f ./.env.production react-scripts build",
    "build:test": "env-cmd -f ./.env react-scripts build",
    ...
  }
  ...
}

Then, into the .env and into the .env.production files we can add an variable:

# .env
...
REACT_APP_TEST_ENV=true

# .env.production
...
REACT_APP_TEST_ENV=false

Now, we can create an component to monitor this env variable and conditional render an element:

const TestOnly = ({ children }) => {
  const isTestingEnv = process.env.REACT_APP_TEST_ENV === 'true';

  if (!isTestingEnv) {
    return null;
  }
  return children;
};

export default TestOnly;

Then, finally, we can encapsulates the feature with the <TestOnly /> component, for example:

return (
  <div>
    <TestOnly>
      <button>This is visible only in test env.</button>
    </TestOnly>
  </div>
);

Django-Rest-Framework e Code Coverage: uma métrica complexa e que não diz muita coisa

Eduardo Oliveira — Fri, 30 Dec 2022 14:32:57 +0000

Uma métrica bastante utilizada para direcionar a escrita de testes, principalmente quando os testes estão sendo escritos para ajudar a garantir a qualidade de uma aplicação já escrita, é a porcentagem de cobertura do código (ou, em inglês, o code coverage).

Segundo [1], code coverage é uma métrica que determina o número de linhas do código que foi validada pelos testes. Essa é uma definição simplista e que não é muito verdadeira.

As ferramentas de code coverage não determinam, de fato, se uma linha foi validada pelos testes, mas sim se ela foi executada durante os testes e existe uma diferença enorme entre ela ser executada e ser validada. Para determinar se essa linha foi, efetivamente, validada é preciso analisar as asserções feitas pelo testes e, se possível, verificar todos os (ou a maioria dos) casos de uso.

Assim sendo, é extramente complexo que uma ferramenta automatizada verifique se uma linha foi, de fato, validada.

Essa introdução levanta alguns pontos sobre ferramentas de cobertura de código em geral que servem para embasar os apontamentos sobre testes com django-rest-framework e essas ferramentas.

Por que verificar a cobertura do código?

O artigo [2] levanta algumas dicas sobre como começar a lidar com code coverage e, dentro dessas dicas, levanta um ponto que é um dos principais motivos para se usar essas ferramentas, mesmo com as ""deficiências"" comentadas acima:

Use coverage reports to identify critical misses in testing

Traduzindo, e adequando, esse trecho quer dizer para "usar relatórios de cobertura para identificar locais críticos sem testes". Por exemplo, veja o caso de uso da imagem abaixo:

Casos onde não foi possível gerar o Token de autenticação, por algum motivo, não foram testados. Assim, é possível analisar o relatório e decidir se esse será um caso recorrente de erro e que deverá estar coberto com novos testes ou se será algum caso raro e que não deve preocupar o time de desenvolvimento.

Django-Rest-Framework

A relação entre os pontos comentados acima com o django-rest-framework é que, o django, principalmente em API's com o rest-framework, adota uma perspectiva declarativa para rotas de API com os ModelViewSet [3] e isso tem algumas implicações importantes na cobertura de códigos.

Quando um CRUD de algum model é definido, de forma declarativa, utilizando o ModelViewSet, conforme o exemplo retirado de [3], o que acontece é que não temos dados de cobertura de código sobre todas as rotas (GET, POST, PUT, PATCH, DELETE) desse determinado recurso:

Desse modo, os relatórios de cobertura de código não dizem muita coisa sobre o que está acontecendo dentro do nosso ModelViewSet. Porém, ainda assim, servem para casos onde você precisa de funcionalidades que sobrescrevem métodos em serializers, models ou no próprio viewset.

Conclusão

A conclusão é que, assim como diversos programadores sempre alertam, cobertura de código é uma métrica que traz problemas se olhada cegamente. Para aplicações que utilizam o django e django-rest-framework (drf) isso deve ser levado, ainda mais, em consideração.

Olhar para um plano de testes (de integração principalmente) tendo o relatório de cobertura de código como uma métrica secundária dentro de aplicações django + drf faz muito mais sentido que olhar apenas para relatório de cobertura para definir o que testar.

Referências

django-storages + S3: lidando com arquivos de mesmo nome

Eduardo Oliveira — Sat, 10 Dec 2022 23:41:01 +0000

O django é um framework para desenvolvimento web na linguagem Python e seu funcionamento é, majoritariamente, baseado em alguns padrões de design, como, por exemplo, os decorators e adapters. O sistema de storage de arquivos de mídia e de arquivos estáticos funciona, de modo simples, seguindo o padrão adapter.

Arquivos de Mídia são os arquivos enviados pelos usuários por meio dos campos de upload de arquivo (ImageField e FileField).

Arquivos Estáticos são os arquivos para serem usados nos layouts (como, por exemplo, scripts, styles e assets).

O django-storages é uma biblioteca que fornece alguns adapters para o sistema de armazenamento do django, enviando arquivos para provedores de nuvem, como a AWS (Amazon Web Service) e a GCP (Google Cloud Platform).

O problema

Utilizando o sistema original de armazenamento, em disco, do django para arquivos estáticos e para arquivos de mídia ao mesmo tempo existem alguns comportamentos que são padrão e que acabam passando sem serem notados:

Durante o upload de arquivos (FileField ou ImageField) quando enviamos dois arquivos com o mesmo nome, por padrão, o adapter de storage adiciona uma parte aleatória no fim do nome do arquivo, permitindo, dessa forma, o upload de ambos sem conflitarem.

Já os arquivos estáticos, aqueles que são "coletados" utilizando o comando python manage.py collectstatic, os conflitos de nomes são resolvidos de uma forma diferente: "o arquivo que for localizado primeiro em uma das localizações especificadas será utilizado" (Ver Referência [1]).

Essa diferença entre os comportamentos, configurações padrões para ambos os adapters, é de suma importância pois, não faz sentido adicionar um jquery_xyz.js, por exemplo, a cada vez que o comando python manage.py collectstatic for executado.

django-storages e a unificação do comportamento

O django-storages, mais especificamente seus adapters S3Boto3Storage e S3StaticStorage, unifica esses dois comportamentos em uma configuração AWS_S3_FILE_OVERWRITE que por padrão é True e de acordo com [2], "por padrão, arquivos com o mesmo nome serão sobrescritos um ao outro. Mude para False para adicionar caracteres extra adicionados".

O problema ainda persiste, pois o comportamento precisa ser diferente para cada um dos adapter. A solução é não alterar a propriedade AWS_S3_FILE_OVERWRITE e sobrescrever o adapter de upload de arquivos de mídia definindo essa configuração localmente:

# core/storages.py
from storages.backends.s3boto3 import S3Boto3Storage

class MediaS3Boto3Storage(S3Boto3Storage):
    file_overwrite = False

Assim, alterando no settings.py a configuração principal:

DEFAULT_FILE_STORAGE = 'core.storages.MediaS3Boto3Storage'

No exemplo, abaixo, o mesmo arquivo foi enviado duas vezes para o bucket S3 e o segundo aparece já com os caracteres acrescentados ao fim do nome:

Observações

Segundo o comentário em [3], não existe a necessidade em, de fato, substituir o adapter e a configuração AWS_S3_FILE_OVERWRITE = False poderia ser utilizada devido ao fato de que o django remove o arquivo antes de criar o novo ao executar o comando python manage.py collectstatic, porém essa é uma questão não confirmada e que, além disso, deixa preocupações, por exemplo, em futuras atualizações do próprio django.

Referências

[1] The staticfiles app - Django Documentation.

[2] Amazon S3 - Django-storages Documentation.

[3] jschneier on GitHub.

django-admin: criando um AdminSite customizado sem perder o registro automático dos Models

Eduardo Oliveira — Fri, 11 Nov 2022 20:50:52 +0000

Ao trabalhar com django, principalmente utilizando o django-admin, é bastante comum não nos preocuparmos, sempre, com os models que são registrados ao painel de admin padrão.

O motivo disso é bem simples: na maioria dos casos não precisamos tocar na instância padrão da classe AdminSite, que é a classe que define como o painel admin irá ser exibido.

Quando não precisamos trocar a instância do AdminSite que utilizamos, o registro automático dos models sempre nos satisfaz.

Porém, ao surgir a necessidade de sobrescrever o AdminSite padrão, costumamos perder o registro automático dos models feitos pelos diversos pacotes (libs, bibliotecas, etc.) que instalamos no nosso projeto.

Motivação

A motivação pra se lidar com esse problema, é que em algumas situações precisamos alterar o AdminSite padrão. Um exemplo clássico e que costuma surgir bastante é: quando é preciso ordenar os Apps e os Models na página inicial do nosso admin.

O AdminSite Padrão

Quando executamos o comando abaixo, para iniciar um novo projeto (existem outras variações do comando, não se preocupe), por padrão, teremos o arquivo core/urls.py do código a seguir

django-admin startproject core .

# core/urls.py
from django.contrib import admin
from django.urls import path

urlpatterns = [
    path('admin/', admin.site.urls),
]

Nesse arquivo, é registrada uma instância padrão do AdminSite que, por sua vez, é importada do caminho: django.contrib.admin.site.

Com o projeto em execução (python manage.py runserver), ao realizar login no painel de admin, teremos a seguinte tela:

Alterando o AdminSite

Para alterar o AdminSite é bem simples, criando um arquivo core/site.py:

# core/site.py
from django.contrib.admin import AdminSite

class CustomSite(AdminSite):
    pass

site = CustomSite()

E alterando, então, o core/urls.py:

# core/urls.py
from django.urls import path
from .site import site

urlpatterns = [
    path('admin/', site.urls),
]

A tela inicial do admin nesse momento, assume uma outra estética, sem permissão pra visualizar ou editar nada (pois não há nenhum model registrado):

AdminSite Padrão

No exemplo acima, substituímos o import do admin.site original pelo .site.admin. Podemos alterar, porém, esse código para substituir o AdminSite padrão do projeto e, dessa forma, não perderemos os models registrados automáticamente:

# core/site.py
from django.contrib.admin import AdminSite

class CustomSite(AdminSite):
    def get_app_list(self, request):
        """
        Return a sorted list of all the installed apps that have been
        registered in this site.
        """
        app_dict = self._build_app_dict(request)

        # Sort the apps alphabetically.
        app_list = sorted(app_dict.values(), key=lambda x: x['name'].lower())

        # Sort the models alphabetically within each app.
        for app in app_list:
            app['models'].sort(key=lambda x: x['name'])
            app['models'].reverse()

        return app_list

Foi adicionado, aqui, um código apenas para alterar a ordem dos models dentro dos apps para que possamos ver efeitos visuais na tela (Referência do código aqui). Além disso, foi removida aquela chamada site = CustomSite().

A partir de agora, é preciso reverter o core/urls.py:

# core/urls.py
from django.contrib import admin
from django.urls import path

urlpatterns = [
    path('admin/', admin.site.urls),
]

Além desses dois passos, é preciso criar um core/apps.py onde será criada uma instância da classe AdminConfig definindo quem é o AdminSite padrão:

# core/apps.py
from django.contrib.admin.apps import AdminConfig

class MyAdminConfig(AdminConfig):
    default_site = 'core.site.CustomSite'

Por último, no settings.py:

# core/settings.py

# ...

INSTALLED_APPS = [
    'django.contrib.admin',
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.messages',
    'django.contrib.staticfiles',
]

# ...

É preciso substituir o django.contrib.admin pelo core.apps.MyAdminConfig:

# core/settings.py

# ...

INSTALLED_APPS = [
    'core.apps.MyAdminConfig',
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.messages',
    'django.contrib.staticfiles',
]

# ...

Resultados

Quando entramos na página inicial do admin agora, temos a seguinte exibição:

Quando alteramos o código comentando a seguinte linha, passamos a ter outro resultado:

# app['models'].reverse()

O código fonte final desse texto está disponível no GitHub.

Referências

The Django admin site - Django Documentation
5. How to set ordering of Apps and models in Django admin dashboard - Django Admin Cookbook

Django + Celery: testando sistemas com filas

Eduardo Oliveira — Tue, 27 Sep 2022 01:45:35 +0000

Esse texto tem o objetivo de descrever como foram implementados os testes com o django e o celery rodando juntos no back-end de um MVP de um produto. Não é objetivo desse texto descrever ou discutir as melhores práticas para testes com filas (melhores práticas, geralmente, dependem de contextos mais amplos), mas sim exemplificar um caso de uso em que precisávamos testar as nossas tarefas de segundo plano.

Conteúdos

Introdução
Objetivos
Exemplo de Usos
Estratégias
Mocks com Unittest
Referências

Introdução

O celery é, de forma bem resumida, um sistema de filas que permite a execução de tarefas em segundo plano.

Imagine, por exemplo, uma aplicação de um fórum que, quando você envia uma requisição POST para comentar um tópico, seu sistema precise enviar um e-mail de notificação para todos os membros que já comentaram no tópico.

Suponha, seguindo o exemplo, que o envio de cada e-mail leve 500 milissegundos e que seu sistema precise enviar 15 e-mails. Perceba que, nessa lógica, se você faz essa requisição e espera o envio dos e-mails, comentar no tópico do seu fórum vai levar cerca de 7 segundos, o que é um tempo muito grande.

Uma forma de contornar isso: filas e processamento paralelo (com o que a gente costuma chamar de workers). O sistema agenda numa fila o envio dos e-mails e termina a requisição devolvendo as informações para o app/front-end. Nesse contexto, o envio dos e-mails será feito "em segundo plano".

Objetivos

Foi feita, até aqui, uma breve descrição do que é o celery e, agora, é importante deixarmos claro algumas coisas: esse texto não tem como objetivo ensinar você a usar o celery em conjunto (ou separado) com o django.

O objetivo desse texto é tratar sobre algumas estratégias de como escrever testes para o django junto com o celery.

Exemplo de Uso

Existem dois conceitos (ou duas formas de fazer a mesma coisa) que precisamos levar em consideração para implementar nossos testes e, portanto, precisamos detalhar isso com um exemplo de uso.

Suponha um model de compras que registra o preço da compra e suponha um outro model de produto que indica o valor vendido em produtos daquele tipo (a modelagem de dados abaixo é só pra exemplificar e não foi elaborada da melhor forma possível) e, para completar, uma tarefa (entenda tarefa como um método, uma função) que executa um cálculo de soma de valores vendidos desse produto específico:

# products/models.py
from decimal import Decimal
from django.db import models

class Product(models.Model):
    name = models.CharField(max_length=100)
    price = models.DecimalField(max_digits=15, decimal_places=2)
    total_purchased_value = models.DecimalField(max_digits=15, decimal_places=2, default=Decimal(0))

    def __str__(self):
        return self.name

    class Meta:
        verbose_name = 'Product'
        verbose_name_plural = 'Products'

class Purchase(models.Model):
    product =  models.ForeignKey(Product, on_delete=models.CASCADE)
    purchase_final_value = models.DecimalField(max_digits=15, decimal_places=2)

    def __str__(self):
        return str(self.product)

    class Meta:
        verbose_name = 'Purchase'
        verbose_name_plural = 'Purchases'

# products/tasks.py
from celery import shared_task

@shared_task(name="calculate_total_purchased_value")
def calculate_total_purchased_value(id_product):
    from app.models import Product, Purchase

    product = Product.objects.filter(pk=id_product).first()
    purchases = Purchase.objects.filter(product=product).all()

    value = 0
    for purchase in purchases:
        value += purchase.purchase_final_value

    product.total_purchased_value = value
    product.save()

Até aqui, é importante perceber que não chamamos a nossa tarefa em nenhum momento e, também, que ela faz um cálculo bem mal feito e que existem formas melhores de fazer isso (Referência Aqui), porém esse exemplo tem apenas o objetivo de mostrar como testar.

Outra questão pertinente é que o import dos models (from app.models import Product, Purchase) em app/tasks.py foi feito dentro do método calculate_total_purchased_value com o objetivo de evitar problemas de dependências circulares, tendo em vista que iremos importar esse método no app/models.py.

Por fim, para a chamada da nossa tarefa ao criar novas purchases, podemos fazer o seguinte:

# products/models.py
from decimal import Decimal
from django.db import models
from app.tasks import calculate_total_purchased_value

class Product(models.Model):
    name = models.CharField(max_length=100)
    price = models.DecimalField(max_digits=15, decimal_places=2)
    total_purchased_value = models.DecimalField(max_digits=15, decimal_places=2, default=Decimal(0))

    def __str__(self):
        return self.name

    class Meta:
        verbose_name = 'Product'
        verbose_name_plural = 'Products'

class Purchase(models.Model):
    product =  models.ForeignKey(Product, on_delete=models.CASCADE)
    purchase_final_value = models.DecimalField(max_digits=15, decimal_places=2)

    def __str__(self):
        return str(self.product)

    def save(self, *args, **kwargs):
        super(Purchase, self).save(*args, **kwargs)

        calculate_total_purchased_value.apply_async(args=[self.product.pk], countdown=2)

    class Meta:
        verbose_name = 'Purchase'
        verbose_name_plural = 'Purchases'

Aqui vamos apenas chamar o método quando algum model Purchase for salvo pois é um exemplo e não precisamos lidar com outros casos de uso (deletar, etc.). A outra consideração é: existem duas formas de executar a tarefa em segundo plano:

.apply_async(): mais completa, os argumentos devem ser passados como o parâmetro args e permite que eu adicione um countdown (tempo para que ela seja executada, referência aqui).
.delay(): não permite countdown ou alguns outros parâmetros, a chamada é bem parecida com a chamada de uma função normal: calculate_total_purchased_value.delay(self.product.pk).

É importante para os próximos passos desse texto, sobre os testes, ter em mente qual dos dois métodos foi usado pois para a estratégia que será utilizada, terá algumas diferenças entre o uso de um ou de outro.

Estratégias

Podemos pensar, de forma básica, em duas estratégias para escrever testes (testar) o nosso processamento paralelo:

Testar se as tarefas estão sendo "enfileiradas", isso é, se o método apply_async ou delay está sendo executado e, depois, testar o método calculate_total_purchased_value separadamente.
Fazer com que ao invés de rodar o processamento paralelo, ele seja executado síncrono e então conseguimos fazer todos os testes como se não existisse processamento em segundo plano.

Nesse texto, iremos tratar da primeira estratégia. Nem sempre é a melhor estratégia, porém, é a que teve menor custo (adequações, cognitivo e de tempo) para ser implementada no projeto no momento em que foi decidido adicionar testes de integração no back-end.

Mocks com unittest

Pra usarmos a estratégia comentada acima (Item 1), o que faremos é: criar um mock para a função apply_async (ou delay) que é adicionada na função da nossa tarefa (pelo decorator do celery). Podemos começar criando um TestCase:

# products/tests.py
from django.test import TestCase
from products.models import Product, Purchase

class TaskTestCase(TestCase):
    def setUp(self):
        self.product = Product.objects.create(name="First Product", price=60)

    def test_save_purchase_call_task(self):
        # TODO
        pass

A próxima coisa que precisamos fazer é criar nosso mock, podemos utilizar o decorator @patch do unittest (referência):

# products/tests.py
# ...
from unittest.mock import patch
# ...

   @patch("products.tasks.calculate_total_purchased_value.apply_async")
    def test_save_purchase_call_task(self, apply_async_mock):
        # TODO
        pass
# ...

Perceba que o parâmetro utilizado dentro do @patch. É o caminho absoluto de importação do app (app do django), arquivo tasks.py, método calculate_total_purchased_value, método apply_async adicionado pelo decorator.

Agora, precisamos criar um item do Purchase para podermos validar se nossa tarefa foi executada:

# products/tests.py
# ...

    @patch("products.tasks.calculate_total_purchased_value.apply_async")
    def test_save_purchase_call_task(self, apply_async_mock):
        item = Purchase()
        item.product = self.product
        item.purchase_final_value = 50
        item.save()
# ...

Finalmente, precisamos fazer a nossa assertion sobre a função apply_async ter sido chamada ou não:

# products/tests.py
# ...

    @patch("products.tasks.calculate_total_purchased_value.apply_async")
    def test_save_purchase_call_task(self, apply_async_mock):
        item = Purchase()
        item.product = self.product
        item.purchase_final_value = 50
        item.save()

        apply_async_mock.assert_called_once_with(args=[self.product.pk], countdown=2)

# ...

Finalmente, rodando um comando python manage.py test, obtemos o incrível resultado esperado:

Agora, podemos testar o outro lado da história (verificar se a tarefa calculate_total_purchased_value faz o que desejamos que ela faça). Vamos continuar utilizando o @patch nesse momento pois vamos precisar criar models Purchase e não queremos que ele chame a tarefa original nesse momento. Fora isso, o processo de testar agora é bem parecido com testar uma função comum:

# products/tests.py
# ...
from products.tasks import calculate_total_purchased_value
# ...


    @patch("products.tasks.calculate_total_purchased_value.apply_async")
    def test_background_task(self, apply_async_mock):
        purchase1 = Purchase()
        purchase1.product = self.product
        purchase1.purchase_final_value = 50
        purchase1.save()

        purchase2 = Purchase()
        purchase2.product = self.product
        purchase2.purchase_final_value = 40
        purchase2.save()

        calculate_total_purchased_value(self.product.pk)

        product = Product.objects.get(id=self.product.pk)

        self.assertEqual(product.total_purchased_value, 90)

# ...

Executando nossos testes novamente, vemos agora dois testes passando:

Nosso arquivo tests.py final ficou dessa forma:

from django.test import TestCase
from unittest.mock import patch
from products.models import Product, Purchase
from products.tasks import calculate_total_purchased_value

class TaskTestCase(TestCase):
    def setUp(self):
        self.product = Product.objects.create(name="First Product", price=60)

    @patch("products.tasks.calculate_total_purchased_value.apply_async")
    def test_save_purchase_call_task(self, apply_async_mock):
        item = Purchase()
        item.product = self.product
        item.purchase_final_value = 50
        item.save()

        apply_async_mock.assert_called_once_with(args=[self.product.pk], countdown=2)

    @patch("products.tasks.calculate_total_purchased_value.apply_async")
    def test_background_task(self, apply_async_mock):
        purchase1 = Purchase()
        purchase1.product = self.product
        purchase1.purchase_final_value = 50
        purchase1.save()

        purchase2 = Purchase()
        purchase2.product = self.product
        purchase2.purchase_final_value = 40
        purchase2.save()

        calculate_total_purchased_value(self.product.pk)

        product = Product.objects.get(id=self.product.pk)

        self.assertEqual(product.total_purchased_value, 90)

Perceba que aqui só escrevemos testes extremamente simples e não estamos nos preocupando com cenários de testes, efeitos colaterais nem nada do gênero, afinal esse texto é apenas um exemplo.

O código escrito nesse texto pode ser encontrado no seguinte repositório: testing-django-celery-tasks.