Barcode Scanner Emulator
Как тестировать ввод со сканера QR-кодов в веб-приложениях
Многие внешние сканеры с поддержкой QR работают в режиме клавиатурного клина и печатают декодированный текст QR в поле с фокусом. Проверьте этот путь, сканируя известную полезную нагрузку и сравнивая её со значением, которое получила страница. Не каждый сканер QR печатает как клавиатура. Последовательные устройства и декодеры камеры — другие интеграции, а события клавиатуры браузера не определяют физический сканер.
QR-код хранит данные. Сканер или декодер камеры превращает эти данные в текст. Веб-приложение должно получить этот текст, решить, когда сканирование закончилось, и проверить его. Это руководство — такая проверка приложения. Создание этикеток, проверка контраста и подтверждение, что устройство умеет декодировать QR Code, описаны в Тестирование QR-кодов: как проверять сканеры QR. Общие формы штрихкодов, включая контрольные цифры EAN, описаны в Как тестировать сканеры штрихкодов в веб-приложениях.
Проверьте ввод со сканера QR за 60 секунд
Возьмите полезную нагрузку, которую выбрали сами, чтобы неверный символ был очевиден. Этот проход использует QR-INPUT-TEST-12345.
- Откройте генератор QR-кодов и создайте QR-код для
QR-INPUT-TEST-12345. Генератор работает в браузере. Он не связывается со сканером. - Подключите сканер с поддержкой QR, который переведён в режим клавиатурного клина. Сканер только 1D не может декодировать этот символ.
- Откройте тестер ввода штрихкода.
- Нажмите Начать тест или щёлкните область сканирования, чтобы у поля был фокус. Тестер сам фокус не забирает и сканер не открывает.
- Отсканируйте QR-код.
- Прочитайте захваченный текст и число символов.
- Сравните этот текст с
QR-INPUT-TEST-12345. Сравнение включает регистр, дефисы и длину. - Прочитайте суффикс. Тестер сообщает ENTER, TAB или Нет, когда сканер отправляет одну из этих клавиш.
Тестер записывает события клавиатуры, которые видит браузер. Он не определяет устройство USB, не читает последовательный порт и не декодирует изображение QR.
Режимы ввода со сканера QR
Один и тот же напечатанный QR-код может прийти через три разные интеграции. Проверка одного режима не затрагивает остальные.
Сканеры QR с клавиатурным клином
В режиме клавиатуры USB HID или в режиме клавиатуры Bluetooth HID операционная система считает сканер клавиатурой. После декодирования сканер печатает полезную нагрузку в элемент, у которого есть фокус. Обычные <input> или <textarea> могут её принять. Страница устройство не открывает. Руководство Клавиатурный клин HID описывает последовательность нажатий, префиксы и суффиксы.
Фокус выбирает назначение. Если элемент с фокусом — это тело документа, кнопка или другой фрейм, слушатели этого поля сканирование не видят.
Последовательные сканеры QR
Сканер USB с последовательным интерфейсом или виртуальным портом COM отправляет декодированный текст байтами процессу, который открыл порт. Фокус этот процесс не выбирает. Поле, которое только слушает нажатия, остаётся пустым, пока терминал на этом порту показывает полезную нагрузку.
Браузеры на основе Chromium могут открыть выбранный пользователем порт через API Web Serial, в безопасном контексте, после жеста пользователя. Firefox и Safari этот API не предоставляют. Сканер-клин не появляется как последовательный порт. Имена портов, baud и кадрирование зависят от устройства и драйвера. USB HID и последовательные сканеры штрихкодов сравнивает два интерфейса. Тестер ввода штрихкода не может читать порт COM.
Сканирование QR камерой
Интеграция с камерой снимает изображение и декодирует QR-код в программе. Страница использует API камеры и декодер. Она не получает события keydown для полезной нагрузки. Приложения камеры телефона, кнопки камеры на странице и аппаратный имиджер, который печатает в поле, — три разных продукта. Пройденная проверка клина не значит, что кнопка камеры работает, а успешное декодирование камерой не значит, что сканер-клин напечатает ту же строку.
Захват ввода со сканера QR с помощью JavaScript
Страница ниже читает одно поле с фокусом. Enter отправляет форму, а кнопка Accept использует тот же обработчик submit, поэтому одно сканирование обрабатывается один раз. Без суффикса ENTER текст остаётся в поле, пока кто-нибудь не нажмёт Accept. Захваченная полезная нагрузка записывается через textContent, поэтому символы вроде < остаются видимыми как текст.
Пример принимает три формата приложения: идентификатор билета вроде QR-INPUT-TEST-12345, URL http или https, либо объект JSON. Он записывает отсканированный текст. Он не переходит по URL, найденному в QR-коде. Сканер, который не отправляет Enter, всё равно работает через кнопку. Tab проходит по подписи, полю и кнопке как обычно, потому что сценарий его не перехватывает.
<!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>
Сохраните файл и откройте его в настольном браузере. Щёлкните поле перед сканированием. autocomplete="off" снижает вероятность, что сохранённое значение подменит сканирование. Подпись и кнопка остаются доступны, поэтому человек может набрать полезную нагрузку без сканера.
Обрабатывайте Enter только в событии submit формы. Второй слушатель keydown для Enter запишет то же сканирование дважды. preventDefault() оставляет браузер на этой странице. Очищайте поле после решения, чтобы следующее сканирование не дописывалось к предыдущему тексту.
Полезная нагрузка QR может содержать перевод строки. Сканер-клин часто печатает этот перевод как Enter. В однострочном поле форма может отправиться на первой строке и отбросить остальное. Используйте textarea или последовательное чтение, которое сохраняет байты, когда приложение должно принимать многострочный текст. Подтвердите это поведение QR-кодом, в полезной нагрузке которого есть перевод строки.
Обработка полезных нагрузок QR
Символ QR не обещает формат приложения. Одна и та же символика может нести любое из этого:
- Обычный текст, например
QR-INPUT-TEST-12345. - URL.
- Идентификатор, выбранный приложением.
- Структурированную полезную нагрузку, например номер билета плюс код места.
- Текст JSON, если приложение задало такую кодировку.
Сканер передаёт декодированные символы. Он не проверяет, что они соответствуют правилу билета, каталогу товаров или схеме JSON. Проверьте строку на странице и проверьте её ещё раз на сервере. Отправленное значение — обычный пользовательский ввод. Браузер не может доказать, что его создал сканер.
Проверка ввода QR
Не считайте полезную нагрузку QR числовой. Правила EAN-13 не применяются. Относитесь к тексту как к недоверенному: показывайте его как текст и не присваивайте его location, innerHTML или URL сценария.
Пустые значения. Голый Enter или Accept на пустом поле не должны создавать запись. trim() также отклоняет полезную нагрузку из одних пробелов.
Неожиданные символы. Сравните полученную строку с известным содержимым QR. Несовпадение раскладки часто меняет знаки препинания, а длина остаётся той же. Отклоняйте символы, которых формат не допускает, и показывайте причину в тексте состояния.
Длина полезной нагрузки. Требуйте максимум, который хранит приложение. maxlength у поля обрезает более длинное сканирование без ошибки. Задавайте его только когда каждая принимаемая полезная нагрузка умещается, и сравнивайте число символов тестера с полем, когда значение выглядит коротким.
Обязательные префиксы. Проверка префикса принадлежит приложению. Это правило билета принимает QR- плюс заглавные буквы, цифры и дефисы:
function isTicketId(value) {
return /^QR-[A-Z0-9-]{1,64}$/.test(value)
}
Срезайте префикс сканера только когда этот сканер настроен отправлять один точный префикс, а приложение его не хранит. Идентификатор символики AIM — это данные, пока вы не решите иначе.
Форматы конкретного приложения. Держите правило рядом с форматом. Форме билета, списку разрешённых URL и объекту JSON нужны разные проверки. Один числовой шаблон отклонит верный текст QR.
Повторные сканирования. Одно физическое сканирование может попасть в два слушателя. Используйте один путь завершения, как в примере. Второе нажатие курка — отдельное событие. Пример отклоняет полезную нагрузку, которую уже принял. Складская форма может вместо этого увеличить количество. Проверьте правило, которое описывает приложение.
Некорректный JSON. JSON.parse бросает ошибку на неполном тексте. Проверьте форму после успешного разбора. Массив или голое число могут быть верным JSON и всё равно иметь неверный тип:
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. Разберите URL, чтобы понять, пригоден ли он, а затем сохраните отсканированную строку, если проверка должна точно совпасть с полезной нагрузкой QR. URL.href может добавить косую черту или изменить кодировку. Принимайте только те схемы, которые задумало приложение. Не открывайте URL как побочный эффект сканирования:
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 }
}
Управляющие символы. Отклоняйте управляющие символы ASCII в клавиатурной полезной нагрузке, чтобы скрытый префикс оставался виден в тексте состояния. CR и LF — управляющие символы. На сканере-клине Enter и Tab — клавиши. В обычном текстовом поле это не символы. Последовательная полезная нагрузка всё ещё может содержать байты 0x0D или 0x0A. Срезайте их на границе последовательного кадрирования и не удаляйте CR, который принадлежит середине многострочной полезной нагрузки.
Суффиксы ENTER и TAB
Суффикс — необязательная настройка сканера. Он не является частью символа QR. Суффиксы ENTER и TAB в сканерах штрихкодов показывает, как отличить клавиши. Прочитайте суффикс в тестере ввода, затем подстройте страницу под сканеры, которые вы разворачиваете.
ENTER отправляет форму однострочного текстового поля в текущих браузерах. Используйте это, когда одно сканирование должно зафиксировать значение. Вызовите preventDefault() на submit, когда страница должна остаться на месте.
TAB переносит фокус на следующий элемент. Читайте значение в keydown, пока у поля ещё есть фокус. Оставьте действие по умолчанию, когда следующее поле должно получить фокус. Игнорируйте Shift+Tab, чтобы с клавиатуры можно было идти назад.
Без суффикса полезная нагрузка остаётся в поле. Кнопка Accept в примере — путь завершения. Таймер бездействия может предположить, что пауза означает конец сканирования. Этот таймер — эвристика: медленная пачка Bluetooth и человек, который печатает быстро, могут пересечь один и тот же промежуток. Предпочитайте настроенный суффикс, когда сценарию нужен жёсткий конец.
CR и LF — это байты. Клавиатурный Enter — это event.key === "Enter". Они не взаимозаменяемы. Слушатель, который только срезает \r из значения поля, не увидит Enter клина, потому что символ так и не был вставлен. Слушатель, который смотрит только на event.key, не разделит последовательный буфер по 0x0D. Некоторые устройства отправляют NumPad Enter. event.key по-прежнему "Enter". Проверяйте event.key, а не только event.code === "Enter".
Суффикс может измениться, когда кто-то сканирует настроечный штрихкод из руководства устройства. После любого изменения настройки снова проверьте Enter, Tab и отсутствие суффикса. Не выдумывайте программирующий штрихкод. Используйте руководство этой модели.
Отладка событий клавиатуры
Когда сохранённый текст неверен, смотрите события в таком порядке.
keydown. Срабатывает для каждой клавиши, включая Enter и Tab, до того как браузер вставит символ или перенесёт фокус. Завершающую клавишу читайте здесь.
input. Срабатывает после того, как печатаемый символ меняет поле. Для Enter или Tab на текстовом поле оно не срабатывает.
event.key. Символ или имя клавиши после того, как операционная система применила раскладку.
event.code. Физическая клавиша, например Digit1 или Numpad1. Она может остаться той же, когда несовпадение раскладки меняет event.key.
Фокус. Запишите document.activeElement до сканирования. Если это не поле QR, остальная трассировка описывает не тот элемент. У iframe свой фокус.
Порядок. При сканировании клином в текстовое поле за печатаемыми событиями keydown идут обновления input, затем финальный keydown для Enter или Tab, если этот суффикс настроен. change срабатывает, когда поле фиксирует значение, обычно при blur. Сканирование, которое оставляет фокус в том же поле, в конце не даёт change. Не используйте change как единственный сигнал завершения.
Время. Сканеры часто заканчивают короткую полезную нагрузку заметно быстрее секунды. Тестер ввода сравнивает средний промежуток между символами с порогом 100 ms и помечает результат как время, а не как опознание оборудования. Быстрый набор, автозаполнение или эмулятор могут оказаться по сторону сканера от этого порога. Задержанное сканирование по Bluetooth может выглядеть как набор. Проверяйте полезную нагрузку и суффикс. Время считайте подсказкой.
Тестер событий клавиатуры перечисляет каждый keydown и keyup с key, code, модификаторами и метками времени. Журнал — это события браузера. Это не сырой трафик USB.
Проверка без физического сканера QR
Логику приложения можно проверить до того, как сканер окажется на столе.
- Введите
QR-INPUT-TEST-12345в поле и нажмите Accept. Это проверяет валидацию и отображение. Это не проверяет декодирование и суффиксы. - Управляйте тем же полем из средства автоматизации браузера, как делает следующий раздел.
- Используйте Barcode Scanner Emulator, когда нужен набор в стиле сканера. Настольное приложение отправляет введённое вами значение, с задержкой набора и суффиксом нет, ENTER или TAB, в приложение с фокусом. Оно воспроизводит клавиатурный путь. Оно не фотографирует изображение QR, не декодирует символ и не создаёт виртуальный порт COM.
Оборудование всё ещё нужно для оптики и поведения устройства: может ли этот сканер прочитать показанный или напечатанный код, включена ли символика QR, какова раскладка, какова настройка суффикса, а также последовательные режимы или режимы SDK производителя. Эмулятор — верная проверка клавиатурного пути. Это неверная проверка, если нужно доказать, что устройство читает конкретный QR-код.
Автоматизация проверок ввода QR
Следующие тесты Playwright управляют страницей примера. Они печатают в поле так, как это сделал бы сканер-клин, а затем проверяют поведение приложения. Они не открывают устройства USB. @playwright/test — зависимость для читателя. Этот сайт её не требует.
Сохраните пример HTML как qr-form.html рядом с этим тестом.
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 вставляет символы в поле с фокусом. Это не USB-устройство. Проверка неожиданного символа использует fill, потому что цель — сообщение проверки и отсутствие внедрённого элемента. Дополните файл случаем URL и случаем JSON, когда эти форматы есть в сборке, которую вы поставляете. Утверждение для URL должно сравнить захваченный текст с исходной строкой QR.
Матрица проверок сканера QR
Выполните их на проверяемом приложении. Страница примера выше покрывает строки билета, URL, JSON, дубликата, пустого значения и неожиданного символа. Приложению только с числами или с несколькими строками нужен свой ожидаемый результат.
| Сценарий | Ожидаемый результат |
|---|---|
| QR с обычным текстом | Получено точное значение |
| QR с URL | Захвачен полный URL, и страница на него не переходит |
| Числовой QR | Цифры сохранены |
| Специальные символы | Получены верные символы |
| Полезная нагрузка JSON | Данные захвачены и проверены |
| Суффикс ENTER | Обработка происходит один раз |
| Суффикс TAB | Поведение фокуса обработано |
| Без суффикса | Приложение использует другой механизм завершения |
| Повторное сканирование | Приложение применяет правила обработки дубликатов |
| Неверная полезная нагрузка | Показана ошибка проверки |
| Нет фокуса | Приложение безопасно обрабатывает отсутствие ввода |
| Длинная полезная нагрузка | Нет непреднамеренного обрезания |
Отсканируйте также полезную нагрузку с переводом строки, если продукт должен её хранить. Запишите, получило ли поле каждую строку.
Устранение неполадок
Начните с известной полезной нагрузки в тестере ввода. Если значение тестера уже неверно, страница — не первая неисправность. Если значение тестера верно, а приложение нет, неисправность в фокусе, проверке или обработке событий. Сканер штрихкодов не работает — более широкий список проверок устройства. Как тестировать ввод со сканера штрихкодов охватывает фокус, раскладку и сценарии POS за пределами этой формы.
Сканер пищит, но ввод не появляется
Сигнал обычно значит, что сканер декодировал символ. Он не значит, что страница получила текст. Подтвердите режим клавиатурного клина. Последовательный режим и режим камеры не печатают в поле. Щёлкните поле, чтобы document.activeElement был этим полем, и отсканируйте снова. Отключённое поле, поле только для чтения или скрытое поле может игнорировать клавиши.
Сканер QR работает в Notepad, но не в браузере
Устройство печатает. Страница эти клавиши не принимает. Проверьте фокус, слушатель keydown, который вызывает preventDefault() на печатаемых клавишах, и слушатель, который обрабатывает только paste. Ввод клина не вызывает событие вставки. Сравните результат тестера с полем приложения.
Сканер читает штрихкоды, но не QR-коды
Устройство может быть только 1D, или символика QR может быть выключена. Страница это не исправит. Подтвердите поддержку 2D и включите QR Code по руководству устройства, используя проверки из Тестирование QR-кодов: как проверять сканеры QR. Успешное сканирование Code 128 доказывает только клавиатурный путь.
Неверные символы
Сначала отсканируйте QR-INPUT-TEST-12345. Если он совпадает, а полезная нагрузка URL или JSON нет, раскладка меняет знаки препинания, такие как :, /, { или ". Сравните event.key с event.code в тестере событий клавиатуры и см. Неверная раскладка клавиатуры сканера штрихкодов. Совместите раскладку сканера с раскладкой операционной системы.
ENTER отправляет форму дважды
Браузер отправляет форму, и слушатель keydown тоже обрабатывает Enter. Оставьте один путь завершения и вызовите на нём preventDefault(). Второе физическое сканирование — другая неисправность. Текст состояния в примере говорит, что полезная нагрузка уже была принята. Если само первое сканирование создаёт две записи, ищите два слушателя, прежде чем менять сканер.
Ввод QR обрезан
Сравните число символов в тестере ввода со значением в поле. Атрибут maxlength, маска ввода или preventDefault() на символьных клавишах могут обрезать строку. Перевод строки внутри полезной нагрузки QR может отправить однострочное поле слишком рано. Некоторые сканеры также ограничивают, сколько символов они печатают. Поднимите этот предел по руководству устройства, когда тестер, а не только приложение, показывает короткое значение. У сканера штрихкодов нет ENTER описывает смежный случай, когда полезная нагрузка приходит, а форма так и не фиксируется.
Сканер не может прочитать QR-код на экране
Убедитесь, что сканер — это 2D-имиджер. Повысьте яркость экрана, увеличьте размер кода и оставьте тихую зону свободной от текста и рамок. Блики, тусклый экран телефона и код, слишком плотный для рабочей дистанции, — оптические проблемы. Напечатайте ту же полезную нагрузку, если чтение с экрана продолжает не удаваться. Проверка приложения всё равно использует известную строку, как только любое сканирование даёт текст.