> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ontime.hosai.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Test with a fake device

> Validate a connector deployment end to end by replaying a realistic terminal session — no hardware required.

The connector ships a script that opens a real TCP socket and replays a realistic F500 session. It exercises the entire path — framing, protocol parsing, HTTPS forwarding, device resolution, deduplication and day reconciliation — without a terminal in the room.

<Tip>
  Run this **before** the hardware arrives. Every configuration mistake you would otherwise discover on installation day — wrong secret, wrong backend URL, unregistered serial, unmapped user — shows up here in thirty seconds.
</Tip>

## Running it

With the connector running:

```bash theme={null}
npm run fake-device -w @ontime/connector
```

Or with explicit values:

```bash theme={null}
LOGSERVER_PORT=7005 \
SERIAL=F500-0002 \
USER_ID=47 \
npm run fake-device -w @ontime/connector
```

| Variable         | Default         | Meaning                                     |
| ---------------- | --------------- | ------------------------------------------- |
| `LOGSERVER_PORT` | `7005`          | The connector's TCP port.                   |
| `SERIAL`         | a sample serial | The device serial to impersonate.           |
| `USER_ID`        | a sample ID     | The terminal user ID the punches come from. |

## What the session contains

The replay sends three messages:

<Steps>
  <Step title="A keepalive">
    Announces the device. This alone should flip a registered device to `Online`.
  </Step>

  <Step title="Two time logs">
    A punch in and a punch out for the given terminal user.
  </Step>
</Steps>

Some scenarios also exercise an admin log — a terminal enrolment event.

## What success looks like

### In the connector's output

Three acknowledgement lines: one for the keepalive, two for the uploaded logs.

<Warning>
  **Missing acknowledgements are the signal.** If the punches are not acknowledged, the connector did not get a success from OnTime — a wrong `CONNECTOR_SECRET` or an unreachable `BACKEND_URL`. That is exactly the failure mode you are testing for.
</Warning>

### In OnTime

<AccordionGroup>
  <Accordion title="The device shows Online" icon="monitor-check">
    **Attendance → Devices.** If the serial was not registered, it appears in the unclaimed list instead — also a correct outcome, and your cue to register it.
  </Accordion>

  <Accordion title="The punches appear" icon="clock">
    On the live board and on the employee's day, **if** the terminal user ID resolves to an employee.
  </Accordion>

  <Accordion title="Or the punches park" icon="inbox">
    If no employee matches the user ID, the punches park as unmapped. **This is a correct outcome, not a failure** — it proves parking works. Map the user and watch them replay.
  </Accordion>

  <Accordion title="The day reconciles" icon="calendar">
    The employee's day record updates with the punch times and hours.
  </Accordion>
</AccordionGroup>

## A useful test sequence

<Steps>
  <Step title="Run it with an unregistered serial">
    Confirms the unclaimed-device path: the serial appears in OnTime and the connector still acknowledges, so a real device's queue would drain rather than back up.
  </Step>

  <Step title="Register the serial, run it again">
    Confirms registration and adoption.
  </Step>

  <Step title="Run it with an unmapped user ID">
    Confirms parking. The punches should be held, not lost and not misattributed.
  </Step>

  <Step title="Map the user, then check the day">
    Confirms replay. The parked punches should apply and the day should reconcile — **without** re-running the script.
  </Step>

  <Step title="Run the same session twice">
    Confirms deduplication. The second run should produce no duplicate punches.
  </Step>
</Steps>

That sequence exercises every rule in the [punch lifecycle](/terminals/punch-lifecycle). If all five behave, the deployment is sound.

## What it does not test

<Note>
  The fake device speaks the protocol correctly by construction. It will not catch a real terminal's firmware quirks, a timezone misconfiguration on the physical device, or network problems between the terminals and the connector host.

  It tests **your side** of the wire thoroughly, and the device's side not at all.
</Note>