Пређи на садржај

Barcode Scanner Emulator

Како тестирати унос скенера QR кодова у веб-апликацијама

Многи спољни скенери са могућношћу QR користе режим тастатурног клина и укуцавају декодирани QR текст у поље у фокусу. Тестирајте тај пут скенирањем познатог корисног садржаја и поређењем са вредношћу коју је страница примила. Не куца сваки QR скенер као тастатура. Серијски уређаји и камерни декодери засебне су интеграције, а догађаји тастатуре веб-прегледача не препознају физички скенер.

QR код чува податке. Скенер, или камерни декодер, те податке претвара у текст. Веб-апликација затим мора да прими тај текст, да одлучи кад је скенирање завршило и да га провери. Овај водич јесте тај тест апликације. Израда налепница, провера контраста и потврда да уређај може да декодира QR Code обрађене су у Тестирање QR кодова: како тестирати скенере QR кодова. Општи обрасци за бар-код, укључујући контролне цифре EAN-а, обрађени су у Како тестирати скенере бар-кодова у веб-апликацијама.

Тестирајте унос QR скенера за 60 секунди

Употребите корисни садржај који сте изабрали, да погрешан знак буде очигледан. Овај пролаз користи QR-INPUT-TEST-12345.

  1. Отворите генератор QR кодова и генеришите QR код за QR-INPUT-TEST-12345. Генератор ради у веб-прегледачу. Не обраћа се скенеру.
  2. Повежите скенер са могућношћу QR који је подешен на режим тастатурног клина. Скенер само за 1D не може да декодира овај симбол.
  3. Отворите страницу тестера уноса бар-кодова.
  4. Кликните на Покрени тест или кликните област скенирања, да поље има фокус. Тестер сам не преузима фокус и не отвара скенер.
  5. Скенирајте QR код.
  6. Прочитајте ухваћени текст и број знакова.
  7. Упоредите тај текст са QR-INPUT-TEST-12345. Подударање укључује велика и мала слова, цртице и дужину.
  8. Прочитајте суфикс. Тестер јавља 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 за корисни садржај. Апликације камере на телефону, дугмад камере на страници и хардверски imager који куца у поље три су различита производа. Пролазак теста клина не значи да дугме камере ради, а успешно декодирање камером не значи да ће клински скенер да укуца исти низ.

Ухватите унос 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 imager. Повећајте светлину екрана, повећајте величину кода и држите тиху зону чистом од текста и оквира. Одсјај, таман екран телефона и код прегуст за радно растојање оптички су проблеми. Одштампајте исти корисни садржај ако читање са екрана и даље не успева. Тест апликације и даље користи познати низ чим било које скенирање произведе текст.