Ir para o conteúdo

Barcode Scanner Emulator

Como testar a entrada do leitor de código QR em aplicativos web

Muitos leitores externos compatíveis com QR usam o modo de cunha de teclado e digitam o texto QR decodificado no campo em foco. Teste esse caminho lendo uma carga conhecida e comparando-a com o valor que a página recebeu. Nem todo leitor de QR digita como um teclado. Dispositivos seriais e decodificadores de câmera são integrações diferentes, e os eventos de teclado do navegador não identificam o leitor físico.

Um código QR armazena dados. O leitor, ou um decodificador de câmera, transforma esses dados em texto. O aplicativo web precisa receber esse texto, decidir quando a leitura terminou e validá-lo. Este guia é esse teste do aplicativo. Gerar etiquetas, conferir o contraste e confirmar que um dispositivo consegue decodificar QR Code está em Teste de código QR: como testar leitores de código QR. Formulários de código de barras em geral, inclusive os dígitos verificadores de EAN, estão em Como testar leitores de código de barras em aplicativos web.

Teste a entrada do leitor de QR em 60 segundos

Use uma carga que você escolheu, para que um caractere errado fique óbvio. Este passo a passo usa QR-INPUT-TEST-12345.

  1. Abra o gerador de código QR e gere um código QR para QR-INPUT-TEST-12345. O gerador roda no navegador. Ele não entra em contato com o leitor.
  2. Conecte um leitor compatível com QR que esteja no modo de cunha de teclado. Um leitor só 1D não consegue decodificar este símbolo.
  3. Abra o testador de entrada de código de barras.
  4. Clique em Iniciar teste ou na área de leitura, para o campo ter foco. O testador não toma o foco sozinho e não abre o leitor.
  5. Leia o código QR.
  6. Leia o texto capturado e a contagem de caracteres.
  7. Compare esse texto com QR-INPUT-TEST-12345. A comparação inclui maiúsculas e minúsculas, hifens e o comprimento.
  8. Leia o sufixo. O testador informa ENTER, TAB ou Nenhum quando o leitor envia uma dessas teclas.

O testador registra eventos de teclado que o navegador consegue ver. Ele não identifica o dispositivo USB, não lê uma porta serial e não decodifica a imagem QR.

Modos de entrada do leitor de QR

O mesmo código QR impresso pode chegar por três integrações diferentes. O teste de um modo não exercita os outros.

Leitores de QR em cunha de teclado

No modo de teclado USB HID, ou no modo de teclado Bluetooth HID, o sistema operacional trata o leitor como um teclado. Depois da decodificação, o leitor digita a carga no controle que tem o foco. Um <input> ou <textarea> normal pode recebê-la. A página não abre o dispositivo. O guia Cunha de teclado HID descreve a sequência de teclas, os prefixos e os sufixos.

O foco decide o destino. Se o elemento em foco for o corpo do documento, um botão ou outro quadro, os listeners deste campo não veem a leitura.

Leitores de QR seriais

Um leitor USB serial ou de porta COM virtual envia o texto decodificado como bytes ao processo que abriu a porta. O foco não escolhe esse processo. Um campo que só escuta teclas fica vazio enquanto um terminal nessa porta mostra a carga.

Navegadores baseados em Chromium podem abrir uma porta escolhida pelo usuário com a API Web Serial, num contexto seguro, depois de um gesto do usuário. Firefox e Safari não oferecem essa API. Um leitor em cunha não aparece como porta serial. Nomes de porta, baud e o enquadramento dependem do dispositivo e do driver. Leitores de código de barras USB HID e serial compara as duas interfaces. O testador de entrada de código de barras não consegue ler uma porta COM.

Leitura de QR por câmera

Uma integração de câmera captura uma imagem e decodifica o código QR em software. A página usa uma API de câmera e um decodificador. Ela não recebe eventos keydown da carga. Apps de câmera do celular, botões de câmera na página e um imager de hardware que digita num campo são três produtos diferentes. Passar num teste de cunha não significa que o botão da câmera funciona, e uma decodificação de câmera bem-sucedida não significa que um leitor em cunha vai digitar a mesma string.

Capturar a entrada do leitor de QR com JavaScript

A página abaixo lê um campo em foco. Enter envia o formulário, e o botão Accept usa esse mesmo handler de submit, então uma leitura é processada uma vez. Sem um sufixo ENTER, o texto fica no campo até alguém ativar Accept. A carga capturada é escrita com textContent, então caracteres como < continuam visíveis como texto.

O exemplo aceita três formatos do aplicativo: um id de ingresso como QR-INPUT-TEST-12345, um URL http ou https, ou um objeto JSON. Ele registra o texto lido. Não navega para um URL encontrado no código QR. Um leitor que não envia Enter ainda funciona pelo botão. Tab percorre o rótulo, o campo e o botão como de costume, porque o script não o prende.

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>QR input example</title>
</head>
<body>
  <form id="qr-form">
    <label for="qr">QR payload</label>
    <input id="qr" name="qr" type="text" autocomplete="off" spellcheck="false">
    <button type="submit">Accept</button>
  </form>
  <p id="status" role="status"></p>
  <pre id="captured"></pre>
  <script>
    const form = document.querySelector('#qr-form')
    const field = document.querySelector('#qr')
    const status = document.querySelector('#status')
    const captured = document.querySelector('#captured')

    if (
      !(form instanceof HTMLFormElement) ||
      !(field instanceof HTMLInputElement) ||
      !(status instanceof HTMLElement) ||
      !(captured instanceof HTMLElement)
    ) {
      throw new Error('QR form markup is missing.')
    }

    const accepted = new Set()

    function classify(raw) {
      if (/[\u0000-\u001F\u007F]/.test(raw)) {
        return { status: 'invalid', message: 'Control character in the QR payload.' }
      }

      const value = raw.trim()
      if (!value) {
        return { status: 'empty' }
      }
      if (value.length > 2048) {
        return { status: 'invalid', message: 'QR payload is longer than this form accepts.' }
      }
      if (/^QR-[A-Z0-9-]{1,64}$/.test(value)) {
        return { status: 'ok', value }
      }
      if (value.startsWith('{')) {
        try {
          const data = JSON.parse(value)
          if (!data || typeof data !== 'object' || Array.isArray(data)) {
            return { status: 'invalid', message: 'QR JSON must be an object.' }
          }
          return { status: 'ok', value }
        } catch {
          return { status: 'invalid', message: 'QR text is not valid JSON.' }
        }
      }
      if (value.startsWith('http://') || value.startsWith('https://')) {
        try {
          const url = new URL(value)
          if (url.protocol !== 'http:' && url.protocol !== 'https:') {
            return { status: 'invalid', message: 'Only http and https URLs are accepted.' }
          }
          return { status: 'ok', value }
        } catch {
          return { status: 'invalid', message: 'The QR text is not a valid URL.' }
        }
      }
      return { status: 'invalid', message: 'Unexpected QR payload.' }
    }

    form.addEventListener('submit', (event) => {
      event.preventDefault()
      const outcome = classify(field.value)
      if (outcome.status === 'empty') {
        status.textContent = 'No QR payload received.'
        field.focus()
        return
      }
      if (outcome.status === 'invalid') {
        status.textContent = outcome.message
        captured.textContent = ''
        field.focus()
        return
      }
      if (accepted.has(outcome.value)) {
        status.textContent = 'Already accepted ' + outcome.value
        field.value = ''
        field.focus()
        return
      }
      accepted.add(outcome.value)
      captured.textContent = outcome.value
      status.textContent = 'Accepted ' + outcome.value
      field.value = ''
      field.focus()
    })
  </script>
</body>
</html>

Salve o arquivo e abra-o num navegador de desktop. Clique no campo antes de ler. autocomplete="off" reduz a chance de um valor salvo substituir a leitura. O rótulo e o botão continuam disponíveis, então uma pessoa pode digitar uma carga sem leitor.

Trate Enter só no evento submit do formulário. Um segundo listener de keydown para Enter registra a mesma leitura duas vezes. preventDefault() mantém o navegador nesta página. Limpe o campo depois de uma decisão para a próxima leitura não se acrescentar ao texto anterior.

Uma carga QR pode conter uma quebra de linha. Um leitor em cunha muitas vezes digita essa quebra como Enter. Num input de uma linha, o formulário pode ser enviado na primeira linha e perder o resto. Use um textarea, ou uma leitura serial que conserve os bytes, quando o aplicativo precisar aceitar texto de várias linhas. Confirme esse comportamento com um código QR cuja carga inclua uma quebra de linha.

Tratamento de cargas QR

Um símbolo QR não promete um formato de aplicativo. A mesma simbologia pode carregar qualquer um destes:

  • Texto simples, como QR-INPUT-TEST-12345.
  • Um URL.
  • Um identificador escolhido pelo aplicativo.
  • Uma carga estruturada, como um número de ingresso mais um código de local.
  • Texto JSON, quando o aplicativo definiu essa codificação.

O leitor transmite os caracteres decodificados. Ele não confere se eles correspondem a uma regra de ingresso, a um catálogo de produtos ou a um esquema JSON. Valide a string na página e valide de novo no servidor. O valor enviado é entrada comum de usuário. O navegador não pode provar que um leitor o produziu.

Validar a entrada de QR

Não presuma que uma carga QR é numérica. As regras de EAN-13 não se aplicam. Trate o texto como não confiável: exiba-o como texto e não o atribua a location, innerHTML ou um URL de script.

Valores vazios. Um Enter sozinho, ou Accept num campo em branco, não deve criar um registro. trim() também rejeita uma carga que contém só espaços.

Caracteres inesperados. Compare a string recebida com o conteúdo QR conhecido. Uma diferença de layout de teclado muitas vezes muda a pontuação enquanto o comprimento permanece o mesmo. Rejeite caracteres que o formato não permite e mostre o motivo no texto de status.

Comprimento da carga. Imponha o máximo que o aplicativo armazena. maxlength no input trunca uma leitura mais longa sem erro. Defina-o só quando toda carga aceita couber, e compare a contagem de caracteres do testador com o campo quando um valor parecer curto.

Prefixos obrigatórios. A conferência de prefixo pertence ao aplicativo. Esta regra de ingresso aceita QR- mais letras maiúsculas, dígitos e hifens:

function isTicketId(value) {
  return /^QR-[A-Z0-9-]{1,64}$/.test(value)
}

Remova um prefixo do leitor só quando esse leitor estiver configurado para enviar um prefixo exato e o aplicativo não o armazenar. Um identificador de simbologia AIM é dado até você decidir o contrário.

Formatos específicos do aplicativo. Mantenha a regra junto do formato. Um formulário de ingresso, uma lista de URLs permitidos e um objeto JSON precisam de conferências diferentes. Um único padrão numérico rejeita texto QR válido.

Leituras duplicadas. Uma leitura física pode atingir dois listeners. Use um único caminho de conclusão, como o exemplo faz. Um segundo acionamento do gatilho é um evento separado. O exemplo rejeita uma carga que já aceitou. Um formulário de depósito pode incrementar uma quantidade. Teste a regra que o aplicativo documenta.

JSON malformado. JSON.parse lança erro em texto incompleto. Confira a forma depois de uma análise bem-sucedida. Um array ou um número solto pode ser JSON válido e ainda assim ser o tipo errado:

function readJsonObject(value) {
  try {
    const data = JSON.parse(value)
    if (!data || typeof data !== 'object' || Array.isArray(data)) {
      return { ok: false, message: 'QR JSON must be an object.' }
    }
    return { ok: true, data }
  } catch {
    return { ok: false, message: 'QR text is not valid JSON.' }
  }
}

URLs inesperados. Analise o URL para ver se ele é utilizável e depois conserve a string lida se o teste precisar corresponder à carga QR com exatidão. URL.href pode acrescentar uma barra ou mudar a codificação. Aceite só os esquemas que o aplicativo pretende. Não abra o URL como efeito colateral da leitura:

function readWebUrl(value) {
  let url
  try {
    url = new URL(value)
  } catch {
    return { ok: false, message: 'The QR text is not a valid URL.' }
  }
  if (url.protocol !== 'http:' && url.protocol !== 'https:') {
    return { ok: false, message: 'Only http and https URLs are accepted.' }
  }
  return { ok: true, value }
}

Caracteres de controle. Rejeite caracteres de controle ASCII numa carga de teclado para que um prefixo oculto continue visível no texto de status. CR e LF são caracteres de controle. Num leitor em cunha, Enter e Tab são teclas. Eles não são caracteres dentro de um input de texto normal. Uma carga serial ainda pode conter bytes 0x0D ou 0x0A. Remova-os na fronteira de enquadramento serial e não remova um CR que pertence ao meio de uma carga de várias linhas.

Sufixos ENTER e TAB

Um sufixo é configuração opcional do leitor. Ele não faz parte do símbolo QR. Sufixos ENTER e TAB em leitores de código de barras mostra como distinguir as teclas. Leia o sufixo no testador de entrada e depois faça a página corresponder aos leitores que você implanta.

ENTER envia o formulário de um campo de texto de uma linha nos navegadores atuais. Use isso quando uma leitura deve confirmar o valor. Chame preventDefault() no submit quando a página deve permanecer no lugar.

TAB move o foco para o controle seguinte. Leia o valor no keydown enquanto o campo ainda tem o foco. Deixe a ação padrão no lugar quando o campo seguinte deve receber o foco. Ignore Shift+Tab para que quem usa o teclado possa voltar.

Sem sufixo deixa a carga no campo. O botão Accept do exemplo é o caminho de conclusão. Um temporizador de inatividade pode supor que uma pausa significa que a leitura terminou. Esse temporizador é uma heurística: uma rajada Bluetooth lenta e quem digita rápido podem cruzar o mesmo intervalo. Prefira um sufixo configurado quando o fluxo precisa de um fim definido.

CR e LF são bytes. Um Enter de teclado é event.key === "Enter". As duas coisas não são intercambiáveis. Um listener que só remove \r de um valor de input não vê um Enter de cunha, porque o caractere nunca foi inserido. Um listener que só observa event.key não divide um buffer serial em 0x0D. Alguns dispositivos enviam NumPad Enter. event.key continua "Enter". Confira event.key, não só event.code === "Enter".

O sufixo pode mudar quando alguém lê um código de barras de configuração do manual do dispositivo. Teste de novo Enter, Tab e a ausência de sufixo depois de qualquer mudança de configuração. Não invente um código de barras de programação. Use o manual desse modelo.

Depurar eventos de teclado

Quando o texto armazenado está errado, inspecione os eventos nesta ordem.

keydown. Dispara para cada tecla, inclusive Enter e Tab, antes de o navegador inserir um caractere ou mover o foco. Leia o terminador aqui.

input. Dispara depois que um caractere imprimível muda o campo. Não dispara para Enter ou Tab num input de texto.

event.key. O caractere ou o nome da tecla depois que o sistema operacional aplica o layout de teclado.

event.code. A tecla física, como Digit1 ou Numpad1. Pode continuar igual quando um layout diferente muda event.key.

Foco. Registre document.activeElement antes da leitura. Se não for o campo de QR, o resto do rastreamento descreve o controle errado. Um iframe tem o próprio foco.

Ordem. Numa leitura em cunha para um campo de texto, eventos keydown imprimíveis são seguidos por atualizações de input e depois um keydown final de Enter ou Tab quando esse sufixo está configurado. change dispara quando o campo confirma, em geral no blur. Uma leitura que deixa o foco no mesmo campo não produz change no fim. Não use change como único sinal de conclusão.

Tempo. Leitores muitas vezes terminam uma carga curta bem abaixo de um segundo. O testador de entrada compara o intervalo médio entre caracteres com um limiar de 100 ms e rotula o resultado como tempo, não como identificação de hardware. Quem digita rápido, o preenchimento automático ou o emulador podem cair do lado do leitor nesse limiar. Uma leitura Bluetooth atrasada pode parecer digitação. Confirme a carga e o sufixo. Trate o tempo como uma pista.

O testador de eventos de teclado lista cada keydown e keyup com key, code, modificadores e marcas de tempo. O registro são eventos do navegador. Não é tráfego USB bruto.

Testar sem um leitor de QR físico

A lógica do aplicativo pode ser testada antes de haver um leitor na mesa.

  • Digite QR-INPUT-TEST-12345 no campo e ative Accept. Isso confere a validação e a exibição. Não confere a decodificação nem os sufixos.
  • Comande o mesmo campo a partir de uma ferramenta de automação do navegador, como a seção seguinte faz.
  • Use o Barcode Scanner Emulator quando precisar de digitação no estilo do leitor. O aplicativo de desktop envia um valor que você informa, com um atraso de digitação e um sufixo de nenhum, ENTER ou TAB, para o aplicativo em foco. Ele reproduz o caminho de teclado. Não fotografa uma imagem QR, não decodifica um símbolo e não cria uma porta COM virtual.

O hardware ainda é necessário para o comportamento óptico e do dispositivo: se aquele leitor consegue ler o código exibido ou impresso, se a simbologia QR está ligada, o layout de teclado, a configuração de sufixo e os modos serial ou SDK do fabricante. O emulador é a conferência certa para o caminho de teclado. É a conferência errada para provar que um dispositivo lê um código QR específico.

Automatizar testes de entrada de QR

Os testes Playwright a seguir comandam a página de exemplo. Eles digitam no campo como um leitor em cunha faria e depois afirmam o comportamento do aplicativo. Não abrem dispositivos USB. @playwright/test é uma dependência de quem lê. Este site não a exige.

Salve o exemplo HTML como qr-form.html ao lado deste teste.

import { readFileSync } from 'node:fs'
import { expect, test } from '@playwright/test'

const html = readFileSync(new URL('./qr-form.html', import.meta.url), 'utf8')

async function openForm(page) {
  await page.setContent(html)
}

test('accepts a known QR payload once', async ({ page }) => {
  await openForm(page)
  const field = page.getByLabel('QR payload')
  await field.pressSequentially('QR-INPUT-TEST-12345')
  await field.press('Enter')
  await expect(page.getByRole('status')).toHaveText('Accepted QR-INPUT-TEST-12345')
  await expect(page.locator('#captured')).toHaveText('QR-INPUT-TEST-12345')
})

test('rejects an unexpected payload', async ({ page }) => {
  await openForm(page)
  const field = page.getByLabel('QR payload')
  await field.pressSequentially('not-a-ticket')
  await field.press('Enter')
  await expect(page.getByRole('status')).toHaveText('Unexpected QR payload.')
  await expect(page.locator('#captured')).toBeEmpty()
})

test('commits on ENTER and rejects a duplicate scan', async ({ page }) => {
  await openForm(page)
  const field = page.getByLabel('QR payload')
  await field.pressSequentially('QR-INPUT-TEST-12345')
  await field.press('Enter')
  await field.pressSequentially('QR-INPUT-TEST-12345')
  await field.press('Enter')
  await expect(page.getByRole('status')).toHaveText('Already accepted QR-INPUT-TEST-12345')
  await expect(page.locator('#captured')).toHaveText('QR-INPUT-TEST-12345')
})

test('does not capture keys while the field is unfocused', async ({ page }) => {
  await openForm(page)
  await page.getByRole('button', { name: 'Accept' }).focus()
  await page.keyboard.type('QR-INPUT-TEST-12345')
  await expect(page.getByLabel('QR payload')).toHaveValue('')
  await expect(page.locator('#captured')).toBeEmpty()
  await expect(page.getByRole('status')).toHaveText('')
})

test('shows unexpected characters as text', async ({ page }) => {
  await openForm(page)
  const payload = '<img src=x onerror=alert(1)>'
  const field = page.getByLabel('QR payload')
  await field.fill(payload)
  await page.getByRole('button', { name: 'Accept' }).click()
  await expect(page.getByRole('status')).toHaveText('Unexpected QR payload.')
  await expect(page.locator('#captured img')).toHaveCount(0)
  await expect(page.locator('img')).toHaveCount(0)
})

pressSequentially insere caracteres no campo em foco. Não é um gadget USB. O teste de caractere inesperado usa fill porque o objetivo é a mensagem de validação e a ausência de um elemento injetado. Estenda o arquivo com um caso de URL e um caso de JSON quando esses formatos estiverem na versão que você entrega. Uma afirmação de URL deve comparar o texto capturado com a string QR original.

Matriz de teste do leitor de QR

Execute estes casos contra o aplicativo em teste. A página de exemplo acima cobre as linhas de ingresso, URL, JSON, duplicata, vazio e caractere inesperado. Um aplicativo só numérico ou de várias linhas precisa do próprio resultado esperado.

Cenário Resultado esperado
QR de texto simples Valor exato recebido
QR de URL URL completo capturado, e a página não navega até ele
QR numérico Dígitos preservados
Caracteres especiais Caracteres corretos recebidos
Carga JSON Dados capturados e validados
Sufixo ENTER O processamento ocorre uma vez
Sufixo TAB Comportamento de foco tratado
Sem sufixo O aplicativo usa um mecanismo alternativo de conclusão
Leitura duplicada O aplicativo aplica as regras de tratamento de duplicatas
Carga inválida Erro de validação exibido
Foco ausente O aplicativo trata a entrada ausente com segurança
Carga longa Sem truncamento indesejado

Leia também uma carga que contenha uma quebra de linha se o produto precisar armazenar uma. Registre se o campo recebeu todas as linhas.

Solução de problemas

Comece com uma carga conhecida no testador de entrada. Se o valor do testador já estiver errado, a página não é a primeira falha. Se o valor do testador estiver certo e o aplicativo estiver errado, a falha é foco, validação ou tratamento de eventos. Leitor de código de barras não funciona é a lista mais ampla do dispositivo. Como testar a entrada do leitor de código de barras cobre foco, layout e fluxos de POS além deste formulário.

O leitor apita, mas nenhuma entrada aparece

Um apito em geral significa que o leitor decodificou um símbolo. Não significa que a página recebeu o texto. Confirme o modo de cunha de teclado. Os modos serial e de câmera não digitam no campo. Clique no campo para que document.activeElement seja esse input e leia de novo. Um campo desativado, somente leitura ou oculto pode ignorar as teclas.

O leitor de QR funciona no Notepad, mas não no navegador

O dispositivo está digitando. A página não está aceitando essas teclas. Confira o foco, um listener de keydown que chama preventDefault() em teclas imprimíveis e um listener que só trata paste. A entrada de cunha não dispara um evento de paste. Compare o resultado do testador com o campo do aplicativo.

O leitor lê códigos de barras, mas não códigos QR

O dispositivo pode ser só 1D, ou a simbologia QR pode estar desligada. A página não consegue corrigir isso. Confirme o suporte a 2D e ative QR Code pelo manual do dispositivo, usando as conferências de Teste de código QR: como testar leitores de código QR. Uma leitura bem-sucedida de Code 128 só prova o caminho de teclado.

Caracteres incorretos

Leia QR-INPUT-TEST-12345 primeiro. Se isso corresponder e uma carga de URL ou JSON não, o layout está mudando a pontuação, como :, /, { ou ". Compare event.key com event.code no testador de eventos de teclado e veja Layout de teclado errado no leitor de código de barras. Faça o layout de teclado do leitor corresponder ao do sistema operacional.

ENTER envia o formulário duas vezes

O navegador envia o formulário, e um listener de keydown também trata Enter. Mantenha um único caminho de conclusão e chame preventDefault() nele. Uma segunda leitura física é uma falha diferente. O texto de status do exemplo diz que a carga já foi aceita. Se a primeira leitura em si cria dois registros, procure dois listeners antes de mudar o leitor.

A entrada de QR é truncada

Compare a contagem de caracteres no testador de entrada com o valor no campo. Um atributo maxlength, uma máscara de input ou preventDefault() em teclas de caractere pode cortar a string. Uma quebra de linha dentro da carga QR pode enviar um input de uma linha cedo demais. Alguns leitores também limitam quantos caracteres digitam. Aumente esse limite pelo manual do dispositivo quando o testador, e não só o aplicativo, mostrar um valor curto. Leitor de código de barras sem ENTER cobre o caso relacionado em que a carga chega e o formulário nunca confirma.

O leitor não consegue ler um código QR na tela

Confirme que o leitor é um imager 2D. Aumente o brilho da tela, aumente o tamanho do código e mantenha a zona de silêncio livre de texto e bordas. Reflexo, uma tela de celular escura e um código denso demais para a distância de trabalho são problemas ópticos. Imprima a mesma carga se a leitura na tela continuar falhando. O teste do aplicativo ainda usa a string conhecida assim que qualquer leitura produzir texto.