lark-app-e2e

Reusable end-to-end test runner and Agent Skill for Feishu/Lark apps. It uses the official lark-cli to send real messages, poll bot replies, run optional application-specific checks, and save a machine-readable report.

The runner is application-agnostic. Test messages, expected replies, and local or remote state assertions live in a small configuration module.

Requirements

• Node.js 20 or newer.
• The official lark-cli.
• A ready user identity from lark-cli auth status --json --verify.
• A running Lark app or bot that the authorized user can message.

Install As A Skill

npx skills add github.com/kairan0/lark-app-e2e -g -y

The repository can also be cloned and run directly.

Quick Start

Create a config based on examples/basic.config.mjs, then list its cases without accessing Lark:

node scripts/run.mjs --config examples/basic.config.mjs --list

Set an exact bot name or P2P chat ID and run one case:

export LARK_E2E_BOT_NAME="My Test Bot"
node scripts/run.mjs \
  --config examples/basic.config.mjs \
  --case health-check

Reports default to data/lark-e2e/latest.json and are ignored by Git.

Config Contract

export default {
  name: "example-app",
  identity: "user",
  chat: {
    id: process.env.LARK_E2E_CHAT_ID || null,
    name: process.env.LARK_E2E_BOT_NAME || null,
  },
  cases: [
    {
      id: "health-check",
      risk: "read-only",
      message: "status",
      expect: {
        minimumBotReplies: 1,
        replyIncludes: ["ready"],
      },
    },
  ],
};

Optional beforeCase(context) and verifyCase(context) hooks can inspect application logs, databases, APIs, or Base state. The context provides runCli, testCase, sourceMessageId, replies, before, and env.

scripts/lark-cli.mjs also exports countBaseRecords() for Base before/after assertions without exposing record contents.

Safety

• Cases default to risk: "read-only".
• Cases marked risk: "write" are blocked unless the caller explicitly passes --allow-write after obtaining user confirmation.
• The runner invokes lark-cli with argv arrays, not shell interpolation.
• Update and Skill notifications are disabled for stable JSON parsing.
• Secrets, copied chat histories, and generated reports must remain outside Git.
• Do not use keychain-downgrade to work around sandboxed macOS Keychain access.

Development

npm test
npm run check

This project takes inspiration from the real-message workflow in feishu-e2e-test, while replacing browser automation with the official CLI and keeping app checks configurable.

License

MIT