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, могат да отворят избран от потребителя порт с Web Serial API, в защитен контекст, след жест на потребителя. 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. В едноредов input формулярът може да се изпрати на първия ред и да изпусне останалото. Използвайте textarea или серийно четене, което пази байтовете, когато приложението трябва да приема многоредов текст. Потвърдете това поведение с QR код, чийто полезен товар включва нов ред.
Обработка на полезни товари от QR
QR символът не обещава формат на приложението. Същата символика може да носи кое да е от следното:
- Обикновен текст, като
QR-INPUT-TEST-12345. - URL.
- Идентификатор, избран от приложението.
- Структуриран полезен товар, като номер на билет плюс код на място.
- Текст JSON, когато приложението е определило това кодиране.
Скенерът предава декодираните знаци. Той не проверява дали отговарят на правило за билет, продуктов каталог или схема JSON. Проверете низа на страницата и го проверете отново на сървъра. Изпратената стойност е обикновено потребителско въвеждане. Браузърът не може да докаже, че я е произвел скенер.
Проверете въвеждането от QR
Не приемайте, че полезният товар на QR е числов. Правилата на EAN-13 не важат. Третирайте текста като недоверен: показвайте го като текст и не го присвоявайте на location, innerHTML или URL на скрипт.
Празни стойности. Гол Enter, или Accept върху празно поле, не трябва да създава запис. trim() отхвърля и полезен товар, който е само интервали.
Неочаквани знаци. Сравнете получения низ с известното съдържание на QR. Несъответствие на подредбата на клавиатурата често променя пунктуацията, докато дължината остава същата. Отхвърлете знаците, които форматът не позволява, и покажете причината в текста на състоянието.
Дължина на полезния товар. Наложете максимума, който приложението съхранява. maxlength на input отрязва по-дълго сканиране без грешка. Задавайте го само когато всеки приет полезен товар се събира, и сравнете броя на знаците в тестера с полето, когато стойност изглежда къса.
Задължителни префикси. Проверката на префикс принадлежи на приложението. Това правило за билет приема 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 са клавиши. Те не са знаци вътре в обикновен текстов input. Сериен полезен товар може все пак да съдържа байтове 0x0D или 0x0A. Махайте ги на границата на серийното кадриране и не махайте CR, който принадлежи към средата на многоредов полезен товар.
Наставки ENTER и TAB
Наставката е незадължителна конфигурация на скенера. Тя не е част от QR символа. Наставки ENTER и TAB при баркод скенери показва как да различите клавишите. Прочетете наставката в тестера за въвеждане, после накарайте страницата да съответства на скенерите, които внедрявате.
ENTER изпраща формуляра на едноредово текстово поле в текущите браузъри. Използвайте това, когато едно сканиране трябва да потвърди стойността. Извикайте preventDefault() върху submit, когато страницата трябва да остане на място.
TAB премества фокуса към следващия контрол. Четете стойността в keydown, докато полето още има фокус. Оставете действието по подразбиране, когато следващото поле трябва да получи фокуса. Пренебрегвайте Shift+Tab, за да може потребител с клавиатура да се върне назад.
Без наставка оставя полезния товар в полето. Бутонът Accept в примера е пътят на завършване. Таймер за неактивност може да предположи, че паузата означава край на сканирането. Този таймер е евристика: бавен пакет по Bluetooth и бърз писач могат да преминат една и съща междина. Предпочитайте настроена наставка, когато процесът се нуждае от твърд край.
CR и LF са байтове. Клавиатурен Enter е event.key === "Enter". Те не са взаимозаменяеми. Слушател, който само маха \r от стойност на input, няма да види Enter от клин, защото знакът никога не е бил вмъкнат. Слушател, който гледа само event.key, няма да раздели сериен буфер по 0x0D. Някои устройства изпращат NumPad Enter. event.key пак е "Enter". Проверявайте event.key, не само event.code === "Enter".
Отстраняване на грешки в клавишните събития
Когато съхраненият текст е грешен, прегледайте събитията в този ред.
keydown. Сработва за всеки клавиш, включително Enter и Tab, преди браузърът да вмъкне знак или да премести фокуса. Четете терминатора тук.
input. Сработва, след като печатаем знак промени полето. Не сработва за Enter или Tab върху текстов input.
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 да е този input, после сканирайте отново. Забранено, само за четене или скрито поле може да пренебрегне клавишите.
QR скенерът работи в Notepad, но не в браузъра
Устройството пише. Страницата не приема тези клавиши. Проверете фокуса, слушател keydown, който вика preventDefault() върху печатаеми клавиши, и слушател, който обработва само paste. Въвеждането с клин не предизвиква събитие 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, маска на input или preventDefault() върху знакови клавиши могат да срежат низа. Нов ред в полезния товар на QR може да изпрати едноредов input твърде рано. Някои скенери също ограничават колко знака изписват. Вдигнете тази граница от ръководството на устройството, когато тестерът, не само приложението, показва къса стойност. На баркод скенера липсва ENTER покрива сродния случай, в който полезният товар пристига, а формулярът никога не се потвърждава.
Скенерът не може да прочете QR код на екрана
Потвърдете, че скенерът е 2D имиджър. Увеличете яркостта на дисплея, увеличете размера на кода и дръжте тихата зона чиста от текст и рамки. Отблясъкът, тъмният екран на телефон и код, твърде плътен за работното разстояние, са оптични проблеми. Отпечатайте същия полезен товар, ако четенето от екрана продължава да се проваля. Тестът на приложението пак използва известния низ, щом което и да е сканиране произведе текст.