@juzi/wechaty 1.0.155 → 1.0.157

package/src/package-json.ts

@@ -4,10 +4,10 @@
  */
 import type { PackageJsonWechaty } from './config'
 
-export const GIT_COMMIT_HASH: string = '6ef3d89f2a44f5454d45c56ff45765c9eeca8a79'
+export const GIT_COMMIT_HASH: string = 'a69947004cdd32876cf204ef4344e10443d444a3'
 export const packageJson: PackageJsonWechaty = {
   "name": "@juzi/wechaty",
-  "version": "1.0.155",
+  "version": "1.0.157",
   "description": "Wechaty is a RPA SDK for Chatbot Makers.",
   "type": "module",
   "exports": {
@@ -116,7 +116,7 @@ export const packageJson: PackageJsonWechaty = {
   },
   "homepage": "https://github.com/wechaty/",
   "dependencies": {
-    "@juzi/wechaty-puppet-service": "1.0.119",
+    "@juzi/wechaty-puppet-service": "1.0.121",
     "clone-class": "^1.1.1",
     "cmd-ts": "^0.10.0",
     "cockatiel": "^2.0.2",
@@ -139,7 +139,7 @@ export const packageJson: PackageJsonWechaty = {
     "@chatie/eslint-config": "^1.0.4",
     "@chatie/semver": "^0.4.7",
     "@chatie/tsconfig": "^4.6.3",
-    "@juzi/wechaty-puppet": "^1.0.143",
+    "@juzi/wechaty-puppet": "^1.0.145",
     "@juzi/wechaty-puppet-mock": "^1.0.1",
     "@swc/core": "1.3.44",
     "@swc/helpers": "^0.3.6",

package/src/user-modules/call.spec.ts

@@ -922,7 +922,11 @@ test('dirty(Call) refreshes user-layer payload so getters see new value', async
   await flush()
 
   t.equal(incoming!.media(), PUPPET.types.CallMediaType.Video, 'media should reflect refreshed payload after dirty')
-  t.ok((puppet.callPayloadDirty as any).called, 'puppet.callPayloadDirty should be invoked')
+  // Note: the handler intentionally does NOT call puppet.callPayloadDirty;
+  // doing so would form a gRPC loop under puppet-service (server bounces the
+  // dirty back through the event stream). Cache invalidation is handled by
+  // the cache-mixin onDirty listener; the user-visible contract is that
+  // .media() above reflects the fresh server value.
 
   await wechaty.stop()
   sandbox.restore()

package/src/user-modules/contact-alias-polling.spec.ts

@@ -0,0 +1,70 @@
+#!/usr/bin/env -S node --no-warnings --loader ts-node/esm
+
+import { test }       from 'tstest'
+import { PuppetMock } from '@juzi/wechaty-puppet-mock'
+
+import { WechatyBuilder } from '../wechaty-builder.js'
+
+/**
+ * Regression: `Contact.alias(newAlias)` invokes
+ *   1. puppet.contactAlias(id, newAlias)    // gRPC write
+ *   2. puppet.contactPayloadDirty(id)       // ONCE, outside the loop  ← BUG
+ *   3. loop 10× { sleep 300ms; puppet.contactPayload(id); check }
+ *
+ * Under puppet-service the first contactPayload() call after a dirty
+ * clears both the LRU and the FlashStore, then refills both with the
+ * fresh fetch. LRU TTL is 15 minutes, so iterations 2..10 hit the LRU
+ * and return iteration-1's payload forever. If the underlying protocol
+ * (puppet-phoenix etc.) was still propagating the alias change at the
+ * moment of iteration 1, the 9 follow-up retries become no-ops and
+ * `alias()` throws "still got old alias after 10 tries".
+ *
+ * The fix moves contactPayloadDirty INTO the loop so every retry
+ * forces a fresh fetch. This test pins that contract: under a forced
+ * stale-read scenario, contactPayloadDirty must be called more than
+ * once.
+ */
+test('alias() must call contactPayloadDirty on every poll iteration', async t => {
+  const puppet = new PuppetMock() as any
+  const wechaty = WechatyBuilder.build({ puppet })
+
+  // Swallow the wechaty-level error the alias() impl re-emits after
+  // its 10 poll iterations all fail to confirm the new alias; without
+  // this, the unhandled 'error' event tears down the test.
+  wechaty.on('error', () => {})
+
+  const mockMe   = puppet.mocker.createContact({ name: 'me' })
+  const mockUser = puppet.mocker.createContact({ name: 'Alice' })
+
+  await wechaty.start()
+  await puppet.mocker.login(mockMe)
+
+  let dirtyCount = 0
+  puppet.contactPayloadDirty = async (_: string) => {
+    dirtyCount++
+  }
+
+  // Simulate the protocol-layer "alias write accepted" but
+  // payload reads keep returning the OLD alias — the exact stuck
+  // scenario the polling loop is supposed to wait out.
+  puppet.contactAlias = async (_id: string, _newAlias: string) => {}
+  puppet.contactPayload = async (id: string) => ({
+    id,
+    alias: 'OLD',
+    name:  'Alice',
+  })
+
+  const contact = await wechaty.Contact.find({ id: mockUser.id })
+  t.ok(contact, 'sanity: find returned a contact')
+
+  // alias() traps internally and emits through wechaty error channel.
+  // We do NOT assert on the throw — only on dirty-call cadence.
+  await contact!.alias('NEW')
+
+  t.ok(
+    dirtyCount > 1,
+    `contactPayloadDirty must be called inside the retry loop, not just once before it; got ${dirtyCount}`,
+  )
+
+  await wechaty.stop()
+})

package/src/user-modules/contact.spec.ts

@@ -20,8 +20,10 @@
  */
 import {
   test,
+  sinon,
 }           from 'tstest'
 
+import type * as PUPPET from '@juzi/wechaty-puppet'
 import { PuppetMock } from '@juzi/wechaty-puppet-mock'
 import { WechatyBuilder } from '../wechaty-builder.js'
 
@@ -88,6 +90,216 @@ test('should throw when instanciate the global class', async t => {
   }, 'should throw when we instanciate a global class')
 })
 
+test('findAllIter() yields every contact returned by contactSearch', async t => {
+  const TOTAL = 7
+
+  const sandbox = sinon.createSandbox()
+  const puppet = new PuppetMock() as any
+  const wechaty = WechatyBuilder.build({ puppet })
+
+  const idList = Array.from({ length: TOTAL }, (_, idx) => `c-${idx}`)
+  const buildPayload = (id: string) => ({ id, name: `name-${id}` } as PUPPET.payloads.Contact)
+
+  sandbox.stub(puppet, 'contactSearch').resolves(idList)
+  sandbox.stub(puppet, 'batchContactPayload').callsFake(async (...args: any[]) => {
+    const ids = args[0] as string[]
+    return new Map(ids.map(id => [ id, buildPayload(id) ]))
+  })
+
+  await wechaty.start()
+  const bot = puppet.mocker.createContact({ name: 'bot' })
+  await puppet.mocker.login(bot)
+
+  const seen: string[] = []
+  for await (const chunk of wechaty.Contact.findAllIter()) {
+    for (const contact of chunk) {
+      seen.push(contact.id)
+    }
+  }
+
+  t.equal(seen.length, TOTAL, `should yield ${TOTAL} contacts`)
+  t.same(seen, idList, 'should yield contacts in search order')
+
+  await wechaty.stop()
+})
+
+test('findAllIter() chunks 101 contacts into [100, 1] at default batch=100', async t => {
+  const TOTAL = 101
+
+  const sandbox = sinon.createSandbox()
+  const puppet = new PuppetMock() as any
+  const wechaty = WechatyBuilder.build({ puppet })
+
+  const idList = Array.from({ length: TOTAL }, (_, idx) => `c-${idx}`)
+  sandbox.stub(puppet, 'contactSearch').resolves(idList)
+  sandbox.stub(puppet, 'batchContactPayload').callsFake(async (...args: any[]) => {
+    const ids = args[0] as string[]
+    return new Map(ids.map(id => [ id, { id, name: id } as PUPPET.payloads.Contact ]))
+  })
+
+  await wechaty.start()
+  const bot = puppet.mocker.createContact({ name: 'bot' })
+  await puppet.mocker.login(bot)
+
+  const sizes: number[] = []
+  for await (const chunk of wechaty.Contact.findAllIter()) {
+    sizes.push(chunk.length)
+  }
+
+  t.same(sizes, [ 100, 1 ], 'should split into two batches: 100 and 1')
+
+  await wechaty.stop()
+})
+
+test('findAllIter() honors early break without throwing', async t => {
+  const TOTAL = 250
+
+  const sandbox = sinon.createSandbox()
+  const puppet = new PuppetMock() as any
+  const wechaty = WechatyBuilder.build({ puppet })
+
+  const idList = Array.from({ length: TOTAL }, (_, idx) => `c-${idx}`)
+  sandbox.stub(puppet, 'contactSearch').resolves(idList)
+  const batchSpy = sandbox.stub(puppet, 'batchContactPayload').callsFake(async (...args: any[]) => {
+    const ids = args[0] as string[]
+    return new Map(ids.map(id => [ id, { id, name: id } as PUPPET.payloads.Contact ]))
+  })
+
+  await wechaty.start()
+  const bot = puppet.mocker.createContact({ name: 'bot' })
+  await puppet.mocker.login(bot)
+
+  let received = 0
+  await t.resolves((async () => {
+    for await (const chunk of wechaty.Contact.findAllIter()) {
+      received += chunk.length
+      if (received >= 100) {
+        break
+      }
+    }
+  })(), 'breaking the loop should not throw')
+
+  t.equal(received, 100, 'should stop after the first batch')
+  t.equal(batchSpy.callCount, 1, 'should not invoke batchContactPayload again after break')
+
+  await wechaty.stop()
+})
+
+test('findAllIter() invokes batchContactPayload ceil(N/batch) times, not N times', async t => {
+  const TOTAL = 100
+  const BATCH = 25
+
+  const sandbox = sinon.createSandbox()
+  const puppet = new PuppetMock() as any
+  const wechaty = WechatyBuilder.build({ puppet })
+
+  const idList = Array.from({ length: TOTAL }, (_, idx) => `c-${idx}`)
+  sandbox.stub(puppet, 'contactSearch').resolves(idList)
+
+  const batchSpy = sandbox.stub(puppet, 'batchContactPayload').callsFake(async (...args: any[]) => {
+    const ids = args[0] as string[]
+    return new Map(ids.map(id => [ id, { id, name: id } as PUPPET.payloads.Contact ]))
+  })
+  const rawSpy = sandbox.spy(puppet, 'contactRawPayload')
+
+  await wechaty.start()
+  const bot = puppet.mocker.createContact({ name: 'bot' })
+  await puppet.mocker.login(bot)
+
+  const rawCountBefore = rawSpy.callCount
+
+  let received = 0
+  for await (const chunk of wechaty.Contact.findAllIter(undefined, { batch: BATCH })) {
+    received += chunk.length
+  }
+
+  t.equal(received, TOTAL, 'should iterate all contacts')
+  t.equal(batchSpy.callCount, Math.ceil(TOTAL / BATCH), `should invoke batchContactPayload ${Math.ceil(TOTAL / BATCH)} times`)
+  t.equal(rawSpy.callCount, rawCountBefore, 'should never fall back to per-id contactRawPayload during iteration')
+
+  await wechaty.stop()
+})
+
+test('findAllIter() with empty contactSearch yields nothing and does not throw', async t => {
+  const sandbox = sinon.createSandbox()
+  const puppet = new PuppetMock() as any
+  const wechaty = WechatyBuilder.build({ puppet })
+
+  sandbox.stub(puppet, 'contactSearch').resolves([])
+  const batchSpy = sandbox.stub(puppet, 'batchContactPayload').resolves(new Map())
+
+  await wechaty.start()
+  const bot = puppet.mocker.createContact({ name: 'bot' })
+  await puppet.mocker.login(bot)
+
+  let chunkCount = 0
+  await t.resolves((async () => {
+    for await (const _chunk of wechaty.Contact.findAllIter()) {
+      chunkCount++
+    }
+  })(), 'empty iteration should not throw')
+
+  t.equal(chunkCount, 0, 'should yield zero chunks')
+  t.equal(batchSpy.callCount, 0, 'should not call batchContactPayload when no ids')
+
+  await wechaty.stop()
+})
+
+test('findAllIter() throws when batch <= 0', async t => {
+  const sandbox = sinon.createSandbox()
+  const puppet = new PuppetMock() as any
+  const wechaty = WechatyBuilder.build({ puppet })
+
+  sandbox.stub(puppet, 'contactSearch').resolves([])
+  sandbox.stub(puppet, 'batchContactPayload').resolves(new Map())
+
+  await wechaty.start()
+  const bot = puppet.mocker.createContact({ name: 'bot' })
+  await puppet.mocker.login(bot)
+
+  for (const badBatch of [ 0, -1 ]) {
+    await t.rejects(
+      (async () => {
+        for await (const _chunk of wechaty.Contact.findAllIter(undefined, { batch: badBatch })) {
+          // should never reach here
+        }
+      })(),
+      /batch must be positive/,
+      `should throw when batch=${badBatch}`,
+    )
+  }
+
+  await wechaty.stop()
+})
+
+test('findAllIter() skips ids missing from payloadMap', async t => {
+  const sandbox = sinon.createSandbox()
+  const puppet = new PuppetMock() as any
+  const wechaty = WechatyBuilder.build({ puppet })
+
+  sandbox.stub(puppet, 'contactSearch').resolves([ 'c1', 'c2', 'c3' ])
+  sandbox.stub(puppet, 'batchContactPayload').resolves(
+    new Map([ [ 'c1', { id: 'c1', name: 'name-c1' } as PUPPET.payloads.Contact ] ]),
+  )
+
+  await wechaty.start()
+  const bot = puppet.mocker.createContact({ name: 'bot' })
+  await puppet.mocker.login(bot)
+
+  const seen: string[] = []
+  await t.resolves((async () => {
+    for await (const chunk of wechaty.Contact.findAllIter()) {
+      for (const contact of chunk) {
+        seen.push(contact.id)
+      }
+    }
+  })(), 'missing ids should not throw or stall iteration')
+
+  t.same(seen, [ 'c1' ], 'should yield only contacts whose payload was returned')
+
+  await wechaty.stop()
+})
+
 test('ProtectedProperties', async t => {
   type NotExistInWechaty = Exclude<ContactProtectedProperty, keyof ContactImpl>
   type NotExistTest = NotExistInWechaty extends never ? true : false

package/src/user-modules/contact.ts

@@ -216,6 +216,73 @@ class ContactMixin extends MixinBase implements SayableSayer {
     return contactList
   }
 
+  /**
+   * Async iterator variant of {@link findAll} that yields contacts in batches.
+   *
+   * Each batch is materialised with a single `puppet.batchContactPayload` RPC,
+   * so iterating N contacts costs roughly `ceil(N / batch)` round trips instead
+   * of N. Uses `puppet.batchContactPayload` directly (required on the puppet
+   * abstract), without holding the whole list in memory or blocking the caller
+   * until every contact has been hydrated. Callers may `break` between batches
+   * to short-circuit.
+   *
+   * @static
+   * @param {string | PUPPET.filters.Contact} [query]
+   * @param {{ batch?: number }} [opts] batch size, default 100
+   * @returns {AsyncIterable<ContactInterface[]>}
+   * @example
+   * for await (const chunk of bot.Contact.findAllIter()) {
+   *   for (const contact of chunk) {
+   *     console.log(contact.name())
+   *   }
+   * }
+   */
+  static async * findAllIter (
+    query? : string | PUPPET.filters.Contact,
+    opts?  : { batch?: number },
+  ): AsyncIterable<ContactInterface[]> {
+    const batch = opts?.batch ?? 100
+    log.verbose('Contact', 'findAllIter(%s, batch=%d)', JSON.stringify(query, stringifyFilter) || '', batch)
+
+    if (batch <= 0) {
+      throw new Error(`Contact.findAllIter() batch must be positive, got ${batch}`)
+    }
+
+    const contactIdList: string[] = await this.wechaty.puppet.contactSearch(query)
+
+    if (!this.wechaty.isLoggedIn) {
+      throw new Error('Contact.findAllIter() requires logged in')
+    }
+
+    for (let i = 0; i < contactIdList.length; i += batch) {
+      const idChunk = contactIdList.slice(i, i + batch)
+
+      const payloadMap = await this.wechaty.puppet.batchContactPayload(idChunk)
+
+      const contactChunk: ContactInterface[] = []
+      for (const id of idChunk) {
+        const payload = payloadMap.get(id)
+        if (!payload) {
+          log.silly('Contact', 'findAllIter() payload missing for id=%s, skip', id)
+          continue
+        }
+
+        const contact: ContactImpl = this.wechaty.puppet.currentUserId === id
+          ? (this.wechaty.ContactSelf as any as typeof ContactSelfImpl).load(id)
+          : (this.wechaty.Contact as any as typeof ContactImpl).load(id)
+
+        contact.payload = payload
+        contactChunk.push(contact)
+      }
+
+      if (contactChunk.length > 0) {
+        yield contactChunk
+      } else {
+        log.warn('Contact', 'findAllIter() batch all missing from payloadMap, idChunk=%j', idChunk)
+      }
+    }
+  }
+
   static async batchLoadContacts (contactIdList: string[]) {
     if (typeof this.wechaty.puppet.batchContactPayload === 'function') {
       const contactList: ContactInterface[] = contactIdList.map(id => {
@@ -496,22 +563,31 @@ class ContactMixin extends MixinBase implements SayableSayer {
 
     try {
       await this.wechaty.puppet.contactAlias(this.id, newAlias)
-      await this.wechaty.puppet.contactPayloadDirty(this.id)
 
       /**
        * In normal puppet, the dirty event handler, onDirty, is a sync function, so the contactPayload will get the new payload
        * However for wechaty-puppet-service, it uses flashstore to cache payloads, and deleting a cache is an async function
-       * So there is a chance contactPayload will still get old contact
+       * So there is a chance contactPayload will still get old contact.
+       *
+       * The puppet LRU TTL (15min) is far longer than the 300ms retry
+       * tick, so a dirty fired ONCE before the loop only invalidates
+       * the cache for iteration 1 — the iteration-1 fetch immediately
+       * refills both LRU and FlashStore, and iterations 2..10 hit the
+       * LRU and return iteration-1's payload forever. Dirty must fire
+       * on every retry so every read goes to source.
        */
       let maxCheck = 10
       let changed = false
       while (maxCheck-- > 0 && !changed) {
-        await new Promise(resolve => {
-          setTimeout(resolve, 300)
-        })
+        await this.wechaty.puppet.contactPayloadDirty(this.id)
         this.payload = await this.wechaty.puppet.contactPayload(this.id)
         const payloadAlias = this.payload.alias || ''
         changed = newAlias === payloadAlias
+        if (!changed) {
+          await new Promise(resolve => {
+            setTimeout(resolve, 300)
+          })
+        }
       }
       if (!changed) {
         throw new Error('failed to modify clias, still got old alias after 10 tries')

package/src/user-modules/room.spec.ts

@@ -232,6 +232,216 @@ test('room.say() smoke testing', async () => {
   await wechaty.stop()
 })
 
+test('Room.findAllIter() yields every room returned by roomSearch', async t => {
+  const TOTAL = 6
+
+  const sandbox = sinon.createSandbox()
+  const puppet = new PuppetMock() as any
+  const wechaty = WechatyBuilder.build({ puppet })
+
+  const idList = Array.from({ length: TOTAL }, (_, idx) => `r-${idx}`)
+  const buildPayload = (id: string) => ({ id, topic: `topic-${id}`, memberIdList: [], adminIdList: [] } as PUPPET.payloads.Room)
+
+  sandbox.stub(puppet, 'roomSearch').resolves(idList)
+  sandbox.stub(puppet, 'batchRoomPayload').callsFake(async (...args: any[]) => {
+    const ids = args[0] as string[]
+    return new Map(ids.map(id => [ id, buildPayload(id) ]))
+  })
+
+  await wechaty.start()
+  const bot = puppet.mocker.createContact({ name: 'bot' })
+  await puppet.mocker.login(bot)
+
+  const seen: string[] = []
+  for await (const chunk of wechaty.Room.findAllIter()) {
+    for (const room of chunk) {
+      seen.push(room.id)
+    }
+  }
+
+  t.equal(seen.length, TOTAL, `should yield ${TOTAL} rooms`)
+  t.same(seen, idList, 'should yield rooms in search order')
+
+  await wechaty.stop()
+})
+
+test('Room.findAllIter() chunks 101 rooms into [100, 1] at default batch=100', async t => {
+  const TOTAL = 101
+
+  const sandbox = sinon.createSandbox()
+  const puppet = new PuppetMock() as any
+  const wechaty = WechatyBuilder.build({ puppet })
+
+  const idList = Array.from({ length: TOTAL }, (_, idx) => `r-${idx}`)
+  sandbox.stub(puppet, 'roomSearch').resolves(idList)
+  sandbox.stub(puppet, 'batchRoomPayload').callsFake(async (...args: any[]) => {
+    const ids = args[0] as string[]
+    return new Map(ids.map(id => [ id, { id, topic: id, memberIdList: [], adminIdList: [] } as PUPPET.payloads.Room ]))
+  })
+
+  await wechaty.start()
+  const bot = puppet.mocker.createContact({ name: 'bot' })
+  await puppet.mocker.login(bot)
+
+  const sizes: number[] = []
+  for await (const chunk of wechaty.Room.findAllIter()) {
+    sizes.push(chunk.length)
+  }
+
+  t.same(sizes, [ 100, 1 ], 'should split into two batches: 100 and 1')
+
+  await wechaty.stop()
+})
+
+test('Room.findAllIter() honors early break without throwing', async t => {
+  const TOTAL = 250
+
+  const sandbox = sinon.createSandbox()
+  const puppet = new PuppetMock() as any
+  const wechaty = WechatyBuilder.build({ puppet })
+
+  const idList = Array.from({ length: TOTAL }, (_, idx) => `r-${idx}`)
+  sandbox.stub(puppet, 'roomSearch').resolves(idList)
+  const batchSpy = sandbox.stub(puppet, 'batchRoomPayload').callsFake(async (...args: any[]) => {
+    const ids = args[0] as string[]
+    return new Map(ids.map(id => [ id, { id, topic: id, memberIdList: [], adminIdList: [] } as PUPPET.payloads.Room ]))
+  })
+
+  await wechaty.start()
+  const bot = puppet.mocker.createContact({ name: 'bot' })
+  await puppet.mocker.login(bot)
+
+  let received = 0
+  await t.resolves((async () => {
+    for await (const chunk of wechaty.Room.findAllIter()) {
+      received += chunk.length
+      if (received >= 100) {
+        break
+      }
+    }
+  })(), 'breaking the loop should not throw')
+
+  t.equal(received, 100, 'should stop after the first batch')
+  t.equal(batchSpy.callCount, 1, 'should not invoke batchRoomPayload again after break')
+
+  await wechaty.stop()
+})
+
+test('Room.findAllIter() invokes batchRoomPayload ceil(N/batch) times, not N times', async t => {
+  const TOTAL = 100
+  const BATCH = 25
+
+  const sandbox = sinon.createSandbox()
+  const puppet = new PuppetMock() as any
+  const wechaty = WechatyBuilder.build({ puppet })
+
+  const idList = Array.from({ length: TOTAL }, (_, idx) => `r-${idx}`)
+  sandbox.stub(puppet, 'roomSearch').resolves(idList)
+
+  const batchSpy = sandbox.stub(puppet, 'batchRoomPayload').callsFake(async (...args: any[]) => {
+    const ids = args[0] as string[]
+    return new Map(ids.map(id => [ id, { id, topic: id, memberIdList: [], adminIdList: [] } as PUPPET.payloads.Room ]))
+  })
+  const rawSpy = sandbox.spy(puppet, 'roomRawPayload')
+
+  await wechaty.start()
+  const bot = puppet.mocker.createContact({ name: 'bot' })
+  await puppet.mocker.login(bot)
+
+  const rawCountBefore = rawSpy.callCount
+
+  let received = 0
+  for await (const chunk of wechaty.Room.findAllIter(undefined, { batch: BATCH })) {
+    received += chunk.length
+  }
+
+  t.equal(received, TOTAL, 'should iterate all rooms')
+  t.equal(batchSpy.callCount, Math.ceil(TOTAL / BATCH), `should invoke batchRoomPayload ${Math.ceil(TOTAL / BATCH)} times`)
+  t.equal(rawSpy.callCount, rawCountBefore, 'should never fall back to per-id roomRawPayload during iteration')
+
+  await wechaty.stop()
+})
+
+test('Room.findAllIter() with empty roomSearch yields nothing and does not throw', async t => {
+  const sandbox = sinon.createSandbox()
+  const puppet = new PuppetMock() as any
+  const wechaty = WechatyBuilder.build({ puppet })
+
+  sandbox.stub(puppet, 'roomSearch').resolves([])
+  const batchSpy = sandbox.stub(puppet, 'batchRoomPayload').resolves(new Map())
+
+  await wechaty.start()
+  const bot = puppet.mocker.createContact({ name: 'bot' })
+  await puppet.mocker.login(bot)
+
+  let chunkCount = 0
+  await t.resolves((async () => {
+    for await (const _chunk of wechaty.Room.findAllIter()) {
+      chunkCount++
+    }
+  })(), 'empty iteration should not throw')
+
+  t.equal(chunkCount, 0, 'should yield zero chunks')
+  t.equal(batchSpy.callCount, 0, 'should not call batchRoomPayload when no ids')
+
+  await wechaty.stop()
+})
+
+test('Room.findAllIter() throws when batch <= 0', async t => {
+  const sandbox = sinon.createSandbox()
+  const puppet = new PuppetMock() as any
+  const wechaty = WechatyBuilder.build({ puppet })
+
+  sandbox.stub(puppet, 'roomSearch').resolves([])
+  sandbox.stub(puppet, 'batchRoomPayload').resolves(new Map())
+
+  await wechaty.start()
+  const bot = puppet.mocker.createContact({ name: 'bot' })
+  await puppet.mocker.login(bot)
+
+  for (const badBatch of [ 0, -1 ]) {
+    await t.rejects(
+      (async () => {
+        for await (const _chunk of wechaty.Room.findAllIter(undefined, { batch: badBatch })) {
+          // should never reach here
+        }
+      })(),
+      /batch must be positive/,
+      `should throw when batch=${badBatch}`,
+    )
+  }
+
+  await wechaty.stop()
+})
+
+test('Room.findAllIter() skips ids missing from payloadMap', async t => {
+  const sandbox = sinon.createSandbox()
+  const puppet = new PuppetMock() as any
+  const wechaty = WechatyBuilder.build({ puppet })
+
+  sandbox.stub(puppet, 'roomSearch').resolves([ 'r1', 'r2', 'r3' ])
+  sandbox.stub(puppet, 'batchRoomPayload').resolves(
+    new Map([ [ 'r1', { id: 'r1', topic: 'topic-r1', memberIdList: [], adminIdList: [] } as PUPPET.payloads.Room ] ]),
+  )
+
+  await wechaty.start()
+  const bot = puppet.mocker.createContact({ name: 'bot' })
+  await puppet.mocker.login(bot)
+
+  const seen: string[] = []
+  await t.resolves((async () => {
+    for await (const chunk of wechaty.Room.findAllIter()) {
+      for (const room of chunk) {
+        seen.push(room.id)
+      }
+    }
+  })(), 'missing ids should not throw or stall iteration')
+
+  t.same(seen, [ 'r1' ], 'should yield only rooms whose payload was returned')
+
+  await wechaty.stop()
+})
+
 test('ProtectedProperties', async t => {
   type NotExistInWechaty = Exclude<RoomProtectedProperty, keyof RoomImpl>
   type NotExistTest = NotExistInWechaty extends never ? true : false