Saltar al contenido

Barcode Scanner Emulator

Cómo probar la entrada de un escáner de códigos QR en aplicaciones web

Muchos escáneres externos capaces de leer QR usan el modo de emulación de teclado y teclean el texto QR decodificado en el campo con el foco. Prueba esa ruta escaneando una carga conocida y comparándola con el valor que recibió la página. No todos los escáneres de códigos QR teclean como un teclado. Los dispositivos seriales y los decodificadores de cámara son integraciones aparte, y los eventos de teclado del navegador no identifican el escáner físico.

Un código QR guarda datos. El escáner, o un decodificador de cámara, convierte esos datos en texto. La aplicación web tiene que recibir ese texto, decidir cuándo termina el escaneo y validarlo. Esta guía es esa prueba de la aplicación. Generar etiquetas, revisar el contraste y confirmar que un equipo puede decodificar QR Code se cubre en Pruebas de códigos QR: cómo probar escáneres de códigos QR. Los formularios de códigos de barras en general, incluidos los dígitos de control EAN, se cubren en Cómo probar escáneres de códigos de barras en aplicaciones web.

Prueba la entrada del escáner de QR en 60 segundos

Usa una carga que hayas elegido, para que un carácter mal puesto se note. Este recorrido usa QR-INPUT-TEST-12345.

  1. Abre el Creador de códigos QR y genera un código QR para QR-INPUT-TEST-12345. El creador corre en el navegador. No contacta al escáner.
  2. Conecta un escáner capaz de leer QR, puesto en modo de emulación de teclado. Un escáner solo 1D no puede decodificar este símbolo.
  3. Abre el Verificador de entrada de códigos de barras.
  4. Haz clic en Iniciar prueba, o haz clic en el área de escaneo, para que el campo tenga el foco. El verificador no toma el foco por su cuenta y no abre el escáner.
  5. Escanea el código QR.
  6. Lee el texto capturado y la cantidad de caracteres.
  7. Compara ese texto con QR-INPUT-TEST-12345. La coincidencia incluye mayúsculas y minúsculas, guiones y longitud.
  8. Lee el sufijo. El verificador informa ENTER, TAB o Ninguno cuando el escáner manda una de esas teclas.

El verificador registra los eventos de teclado que el navegador puede ver. No identifica el dispositivo USB, no lee un puerto serial y no decodifica la imagen QR.

Modos de entrada del escáner de QR

El mismo código QR impreso puede llegar por tres integraciones distintas. La prueba de un modo no ejercita los otros.

Escáneres de QR con emulación de teclado

En modo teclado HID USB, o en modo teclado HID Bluetooth, el sistema operativo trata al escáner como un teclado. Después de decodificar, el escáner teclea la carga en el control que tiene el foco. Un <input> o un <textarea> normal puede recibirla. La página no abre el dispositivo. La guía Emulación de teclado HID describe la secuencia de teclazos, los prefijos y los sufijos.

El foco decide el destino. Si el elemento con el foco es el cuerpo del documento, un botón u otro marco, los manejadores de este campo no ven el escaneo.

Escáneres de QR seriales

Un escáner serial USB o de puerto COM virtual manda el texto decodificado como bytes al proceso que abrió el puerto. El foco no elige ese proceso. Un campo que solo escucha teclazos se queda vacío mientras una terminal en ese puerto muestra la carga.

Los navegadores basados en Chromium pueden abrir un puerto que eligió el usuario con la Web Serial API, en un contexto seguro, después de un gesto del usuario. Firefox y Safari no ofrecen esa API. Un escáner en emulación no aparece como puerto serial. Los nombres de puerto, la tasa de baudios y el encuadre dependen del equipo y del controlador. Escáneres de códigos de barras USB HID y serial compara las dos interfaces. El Verificador de entrada de códigos de barras no puede leer un puerto COM.

Lectura de QR con cámara

Una integración de cámara captura una imagen y decodifica el código QR en software. La página usa una API de cámara y un decodificador. No recibe eventos keydown para la carga. Las apps de cámara del teléfono, los botones de cámara en la página y un escáner de imagen de hardware que teclea en un campo son tres productos distintos. Pasar una prueba de emulación no significa que el botón de cámara funcione, y una decodificación de cámara correcta no significa que un escáner en emulación teclee la misma cadena.

Capturar la entrada del escáner de QR con JavaScript

La página de abajo lee un solo campo con el foco. Enter manda el formulario, y el botón Accept usa ese mismo manejador de submit, así que un escaneo se procesa una vez. Sin sufijo ENTER, el texto se queda en el campo hasta que alguien activa Accept. La carga capturada se escribe con textContent, así que caracteres como < siguen visibles como texto.

El ejemplo acepta tres formatos de la app: un identificador de ticket como QR-INPUT-TEST-12345, una URL http o https, o un objeto JSON. Registra el texto escaneado. No navega a una URL encontrada en el código QR. Un escáner que no manda Enter sigue funcionando con el botón. Tab recorre la etiqueta, el campo y el botón como siempre, porque el script no lo atrapa.

<!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>

Guarda el archivo y ábrelo en un navegador de escritorio. Haz clic en el campo antes de escanear. autocomplete="off" baja la posibilidad de que un valor guardado reemplace el escaneo. La etiqueta y el botón siguen disponibles, así que una persona puede teclear una carga sin escáner.

Maneja Enter solo en el evento submit del formulario. Un segundo manejador keydown para Enter registra el mismo escaneo dos veces. preventDefault() mantiene el navegador en esta página. Vacía el campo después de una decisión para que el siguiente escaneo no se pegue al texto anterior.

Una carga QR puede contener un salto de línea. Un escáner en emulación suele teclear ese salto como Enter. En un input de una línea, el formulario puede enviarse en la primera línea y perder el resto. Usa un textarea, o un programa que lee el puerto serial y conserva los bytes, cuando la app deba aceptar texto de varias líneas. Confirma ese comportamiento con un código QR cuya carga incluya un salto de línea.

Manejar las cargas QR

Un símbolo QR no promete un formato de la app. La misma simbología puede llevar cualquiera de estos:

  • Texto simple, como QR-INPUT-TEST-12345.
  • Una URL.
  • Un identificador elegido por la app.
  • Una carga estructurada, como un número de ticket más un código de ubicación.
  • Texto JSON, cuando la app definió esa codificación.

El escáner transmite los caracteres decodificados. No revisa que coincidan con una regla de ticket, un catálogo de productos o un esquema JSON. Valida la cadena en la página y valídala otra vez en el servidor. El valor enviado es entrada de usuario común. El navegador no puede demostrar que lo produjo un escáner.

Validar la entrada QR

No des por hecho que una carga QR es numérica. Las reglas EAN-13 no aplican. Trata el texto como no confiable: muéstralo como texto y no lo asignes a location, innerHTML o una URL de script.

Valores vacíos. Un Enter solo, o Accept en un campo en blanco, no debe crear un registro. trim() también rechaza una carga que solo son espacios.

Caracteres inesperados. Compara la cadena recibida con el contenido QR conocido. Un diseño de teclado que no coincide suele cambiar la puntuación mientras la longitud se mantiene. Rechaza los caracteres que el formato no permite y muestra el motivo en el texto de estado.

Longitud de la carga. Aplica el máximo que guarda tu app. maxlength en el input recorta un escaneo más largo sin error. Ponlo solo cuando cada carga aceptada cabe, y compara la cantidad de caracteres del verificador con el campo cuando un valor se ve corto.

Prefijos obligatorios. Una revisión de prefijo pertenece a la app. Esta regla de ticket acepta QR- más letras mayúsculas, dígitos y guiones:

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

Quita un prefijo del escáner solo cuando ese escáner está configurado para mandar un prefijo exacto y la app no lo guarda. Un identificador de simbología AIM es un dato hasta que decidas lo contrario.

Formatos propios de la app. Deja la regla junto al formato. Un formulario de ticket, una lista de URL permitidas y un objeto JSON necesitan revisiones distintas. Un solo patrón numérico va a rechazar texto QR válido.

Escaneos duplicados. Un escaneo físico puede pegarle a dos manejadores. Usa un solo camino para completar, como hace el ejemplo. Otro jalón del gatillo es un evento aparte. El ejemplo rechaza una carga que ya aceptó. Un formulario de bodega podría subir una cantidad en su lugar. Prueba la regla que documenta tu app.

JSON mal formado. JSON.parse lanza un error con texto incompleto. Revisa la forma después de un análisis correcto. Un array o un número suelto pueden ser JSON válido y seguir siendo el tipo incorrecto:

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.' }
  }
}

URL inesperadas. Analiza la URL para ver si sirve y conserva la cadena escaneada si la prueba debe coincidir exactamente con la carga QR. URL.href puede agregar una barra o cambiar la codificación. Acepta solo los esquemas que la app pretende. No abras la URL como efecto secundario del escaneo:

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 control. Rechaza los caracteres de control ASCII en una carga de teclado para que un prefijo oculto siga visible en el texto de estado. CR y LF son caracteres de control. En un escáner en emulación, Enter y Tab son teclas. No son caracteres dentro de un input de texto normal. Una carga serial puede contener de todos modos bytes 0x0D o 0x0A. Quítalos en el límite de encuadre serial y no quites un CR que pertenece al medio de una carga de varias líneas.

Sufijos ENTER y TAB

Un sufijo es configuración opcional del escáner. No forma parte del símbolo QR. Sufijos ENTER y TAB en los escáneres de códigos de barras muestra cómo distinguir las teclas. Lee el sufijo en el verificador de entrada y haz que la página coincida con los escáneres que despliegas.

ENTER manda el formulario de un campo de texto de una línea en los navegadores actuales. Úsalo cuando un escaneo deba confirmar el valor. Llama a preventDefault() en submit cuando la página deba quedarse en su lugar.

TAB mueve el foco al control siguiente. Lee el valor en keydown mientras el campo todavía tiene el foco. Deja la acción predeterminada en su lugar cuando el campo siguiente deba recibir el foco. Ignora Shift+Tab para que quien usa el teclado pueda regresar.

Sin sufijo deja la carga en el campo. El botón Accept del ejemplo es el camino para completar. Un temporizador de inactividad puede suponer que una pausa significa que el escaneo terminó. Ese temporizador es una heurística: una ráfaga Bluetooth lenta y quien teclea rápido pueden cruzar el mismo hueco. Prefiere un sufijo configurado cuando el flujo necesita un final firme.

CR y LF son bytes. Un Enter de teclado es event.key === "Enter". No son intercambiables. Un manejador que solo quita \r de un valor de input no va a ver un Enter de emulación, porque el carácter nunca se insertó. Un manejador que solo observa event.key no va a partir un búfer serial en 0x0D. Algunos equipos mandan NumPad Enter. event.key sigue siendo "Enter". Revisa event.key, no solo event.code === "Enter".

El sufijo puede cambiar cuando alguien escanea un código de barras de configuración del manual del equipo. Vuelve a probar Enter, Tab y la ausencia de sufijo después de cualquier cambio de configuración. No inventes un código de barras de programación. Usa el manual de ese modelo.

Depurar eventos de teclado

Cuando el texto guardado está mal, revisa los eventos en este orden.

keydown. Se dispara para cada tecla, incluidas Enter y Tab, antes de que el navegador inserte un carácter o mueva el foco. Lee el terminador aquí.

input. Se dispara después de que un carácter imprimible cambia el campo. No se dispara para Enter o Tab en un input de texto.

event.key. El carácter o el nombre de tecla después de que el sistema operativo aplica el diseño de teclado.

event.code. La tecla física, como Digit1 o Numpad1. Puede seguir igual cuando un diseño que no coincide cambia event.key.

Foco. Registra document.activeElement antes del escaneo. Si no es el campo QR, el resto del rastro describe el control equivocado. Un iframe tiene su propio foco.

Orden. En un escaneo de emulación hacia un campo de texto, a los eventos keydown imprimibles les siguen actualizaciones input y luego un keydown final para Enter o Tab cuando ese sufijo está configurado. change se dispara cuando el campo confirma el valor, normalmente al perder el foco. Un escaneo que deja el foco en el mismo campo no produce change al final. No uses change como única señal para completar.

Tiempo. Los escáneres suelen terminar una carga corta bastante por debajo de un segundo. El verificador de entrada compara el hueco promedio entre caracteres con un umbral de 100 ms y etiqueta el resultado como tiempo, no como identificación del hardware. Quien teclea rápido, el autocompletado o el emulador pueden caer del lado del escáner de ese umbral. Un escaneo Bluetooth retrasado puede parecer tecleo. Revisa la carga y el sufijo. Trata el tiempo como una pista.

El Inspector de eventos de teclado lista cada keydown y keyup con key, code, modificadores y marcas de tiempo. El registro son eventos del navegador. No es tráfico USB en crudo.

Probar sin un escáner de QR físico

La lógica de la app se puede probar antes de que haya un escáner en el escritorio.

  • Teclea QR-INPUT-TEST-12345 en el campo y activa Accept. Eso revisa la validación y la presentación. No revisa la decodificación ni los sufijos.
  • Controla el mismo campo desde una herramienta de automatización del navegador, como hace la sección siguiente.
  • Usa Barcode Scanner Emulator cuando necesites tecleo al estilo del escáner. La app de escritorio manda un valor que escribes, con un retraso de tecleo y un sufijo de ninguno, ENTER o TAB, a la aplicación con el foco. Reproduce la ruta de teclado. No fotografía una imagen QR, no decodifica un símbolo y no crea un puerto COM virtual.

El hardware sigue haciendo falta para el comportamiento óptico y del equipo: si ese escáner puede leer el código en pantalla o impreso, si la simbología QR está activada, el diseño de teclado, la configuración del sufijo y los modos seriales o SDK del fabricante. El emulador es la revisión correcta para la ruta de teclado. Es la revisión incorrecta para demostrar que un equipo lee un código QR en particular.

Automatizar las pruebas de entrada QR

Las pruebas de Playwright siguientes controlan la página de ejemplo. Teclean en el campo como lo haría un escáner en emulación y luego revisan el comportamiento de la app. No abren dispositivos USB. @playwright/test es una dependencia de quien ejecuta la prueba. Este sitio no la exige.

Guarda el ejemplo HTML como qr-form.html junto a esta prueba.

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 inserta caracteres en el campo con el foco. No es un dispositivo USB. La prueba de caracteres inesperados usa fill porque el objetivo es el mensaje de validación y que no haya un elemento inyectado. Amplía el archivo con un caso de URL y un caso de JSON cuando esos formatos estén en la versión que entregas. Una aserción de URL debe comparar el texto capturado con la cadena QR original.

Matriz de prueba del escáner de QR

Ejecútalas contra la app bajo prueba. La página de ejemplo de arriba cubre las filas de ticket, URL, JSON, duplicado, vacío y caracteres inesperados. Una app solo numérica o de varias líneas necesita su propio resultado esperado.

Escenario Resultado esperado
QR de texto simple Valor exacto recibido
QR de URL URL completa capturada, y la página no navega hasta ella
QR numérico Dígitos conservados
Caracteres especiales Caracteres correctos recibidos
Carga JSON Datos capturados y validados
Sufijo ENTER El procesamiento ocurre una vez
Sufijo TAB Comportamiento del foco resuelto
Sin sufijo La app usa otro mecanismo para completar
Escaneo duplicado La app aplica las reglas de duplicados
Carga no válida Error de validación mostrado
Foco ausente La app maneja la entrada ausente de forma segura
Carga larga Sin recorte no deseado

Escanea también una carga que contenga un salto de línea si el producto debe guardar uno. Anota si el campo recibió cada línea.

Resolución de problemas

Empieza con una carga conocida en el verificador de entrada. Si el valor del verificador ya está mal, la página no es la primera falla. Si el valor del verificador está bien y la app no, la falla es el foco, la validación o el manejo de eventos. El escáner de códigos de barras no funciona es la lista de revisión más amplia del equipo. Cómo probar la entrada de un escáner de códigos de barras cubre el foco, el diseño y los flujos de POS más allá de este formulario.

El escáner emite un pitido, pero no aparece ninguna entrada

Un pitido suele significar que el escáner decodificó un símbolo. No significa que la página recibió el texto. Confirma el modo de emulación de teclado. Los modos serial y de cámara no teclean en el campo. Haz clic en el campo para que document.activeElement sea ese input y escanea otra vez. Un campo desactivado, de solo lectura u oculto puede ignorar las teclas.

El escáner de QR funciona en Notepad, pero no en el navegador

El equipo está tecleando. La página no acepta esas teclas. Revisa el foco, un manejador keydown que llama a preventDefault() en teclas imprimibles y un manejador que solo trata paste. La entrada de emulación no dispara un evento paste. Compara el resultado del verificador con el campo de la app.

El escáner lee códigos de barras, pero no códigos QR

El equipo puede ser solo 1D, o la simbología QR puede estar desactivada. La página no puede arreglar eso. Confirma el soporte 2D y activa QR Code desde el manual del equipo, con las revisiones de Pruebas de códigos QR: cómo probar escáneres de códigos QR. Un escaneo correcto de Code 128 solo demuestra la ruta de teclado.

Caracteres incorrectos

Escanea primero QR-INPUT-TEST-12345. Si coincide y una carga URL o JSON no, el diseño está cambiando puntuación como :, /, { o ". Compara event.key con event.code en el Inspector de eventos de teclado y mira Diseño de teclado incorrecto en el escáner de códigos de barras. Iguala el diseño de teclado del escáner con el del sistema operativo.

ENTER manda el formulario dos veces

El navegador manda el formulario y un manejador keydown también trata Enter. Quédate con un camino para completar y llama ahí a preventDefault(). Un segundo escaneo físico es una falla distinta. El texto de estado del ejemplo dice que la carga ya fue aceptada. Si el primer escaneo en sí crea dos registros, busca dos manejadores antes de cambiar el escáner.

La entrada QR se corta

Compara la cantidad de caracteres del verificador de entrada con el valor del campo. Un atributo maxlength, una máscara de entrada o preventDefault() en teclas de caracteres puede cortar la cadena. Un salto de línea dentro de la carga QR puede mandar pronto un input de una línea. Algunos escáneres también limitan cuántos caracteres teclean. Sube ese límite desde el manual del equipo cuando el verificador, no solo la app, muestre un valor corto. Al escáner de códigos de barras le falta ENTER cubre el caso relacionado en el que la carga llega y el formulario nunca confirma.

El escáner no puede leer un código QR en la pantalla

Confirma que el escáner es de imagen 2D. Sube el brillo de la pantalla, agranda el código y mantén la zona de silencio libre de texto y bordes. El reflejo, una pantalla de teléfono tenue y un código demasiado denso para la distancia de trabajo son problemas ópticos. Imprime la misma carga si la lectura en pantalla sigue fallando. La prueba de la app sigue usando la cadena conocida en cuanto cualquier escaneo produce texto.