Como fazer um tour que não quebra quando a tela muda

Um tour depende de achar o elemento certo na tela. E a tela muda: o botão troca de lugar, a classe do CSS muda, o layout é refeito. Se o tour aponta para o lugar errado, ou não aponta para nada, ninguém avisa.

Atributo estável é melhor que seletor adivinhado

Seletor por classe ou por posição quebra a cada ajuste de layout. O caminho mais firme é um atributo posto de propósito no elemento:

<button data-onboara="cobrancas.nova">Nova cobrança</button>

Sem acesso ao código, dá para começar pelo que a tela oferece: papel, nome acessível e texto do elemento. O importante é ter um caminho para endurecer a âncora depois.

Cuidado com o data-testid

Parece um bom atalho, mas tem um risco pouco conhecido: a opção reactRemoveProperties do compilador do Next.js remove do build os atributos que começam com data-test. Se o tour depende deles, ele pode funcionar em desenvolvimento e quebrar inteiro em produção. Por isso, use um atributo só para isso.

Trate o elemento que some

Um alvo pode não existir para aquela pessoa, por causa de permissão ou de configuração. O tour não pode travar por isso: pula o passo e segue, e a contagem “Passo N de M” considera só os passos visíveis.

Saiba quando quebrou

Sem acesso ao código do seu sistema, a defesa é medir em produção. Quando um alvo deixa de ser achado, isso tem de chegar a quem cuida do fluxo, antes de chegar ao suporte.