Tiktest

tiktest

automated tiktok-style video review of every pr.

the more i shipped stuff with claude the more i realised; in the long term the most value i can add as a human is testing - finding the stuff other humans would struggle with...

...but testing is boring. so i tried to make it less boring - or at least take way less of my time.

play with sound to hear narration and watch normal speed

get it running in a few mins

two paths. both are paste-and-go — claude code does the wiring.

1. claude code plugin — record a walkthrough of whatever you just shipped, locally. type these slash commands yourself (claude can't invoke them from inside a prompt), one at a time:

/plugin marketplace add marcushyett/tik-test
/plugin install tiktest@tiktest
/reload-plugins

then paste this prompt so claude finishes the wiring:

The tik-test Claude Code plugin is now installed. Finish setting it up for this project:
1. Verify the plugin's runtime prereqs are present and fix what's missing for my OS:
   - `ffmpeg` on PATH (`brew install ffmpeg` on macOS, `sudo apt install ffmpeg` on Linux)
   - Playwright Chromium (`npx playwright install chromium`)
   - `tik-test` CLI globally (`npm i -g tik-test`)
2. If a `tiktest.md` already exists at repo root, summarise it and ask me whether to keep, expand, or replace it before doing anything destructive. Otherwise run `/tiktest:setup` and ask me for anything you can't infer (project name, dev-server start command, login/auth flow, key user paths to record).
3. Tell me how to invoke `/tiktest:run` (full video, MP4 to Desktop) and `/tiktest:quick` (checklist only, no video) when I ship a feature, including the optional URL / focus-hint argument forms.

2. github action — cd into your repo, open claude code, paste:

Set up tik-test (https://github.com/marcushyett/tik-test — 45s video reviews on every PR) on this repo. Goal: working tik-test.yml + drafted tiktest.md + secret instructions, then test on a real PR.
1. Pick a template (local-dev / vercel-preview / staging-with-services) from inspecting package.json, framework configs, and deploy setup; ask if ambiguous. Create .github/workflows/tik-test.yml from it, adapted (build cmd, dev port, working-directory).
2. Draft tiktest.md at repo root: read README + package.json + 5-10 representative source files to infer flows; detect login (ask me for creds if there's a wall); list 3-5 highest-risk user-facing surfaces. Format: one-paragraph app description → login → "Risky surfaces" bullets → optional "Hints" with test-IDs. Show me the draft and wait for confirmation before committing. Warn if CLAUDE.md / AGENTS.md sit alongside it (silent-fallback footgun).
3. List the secrets I need to add: CLAUDE_CODE_OAUTH_TOKEN (`claude setup-token`, required) plus optionals you detect apply (OPENAI_API_KEY for narration; VERCEL_AUTOMATION_BYPASS_SECRET if Vercel Deployment Protection is on). One line each on where to get them. Mention that TIKTEST_OWNERS in repo Variables can restrict who triggers runs (default = any collaborator).
4. Open the PR. Heads-up: tik-test's plan generator looks at the diff and will skip cleanly with a "no testable change" comment when the only edits are workflow + tiktest.md (no impact on the UI). That's expected, not a failure — the action itself is wired up correctly.
5. After I merge it, propose a small visible UI change (one-screen nit from open issues or your own suggestion) to be the real first test PR. Wait for my okay, then ship on a separate branch.

prerequisites

optional: OPENAI_API_KEY for voice narration, VERCEL_AUTOMATION_BYPASS_SECRET for protected previews.

telling tik-test how to test your app

drop a tiktest.md at your repo root. free-form prose, no schema:

# acme

acme is a project tracker for engineering teams.

login: email `review-bot@acme.app`, password `hunter2`. click the
"sign in with email" button on the landing page; the app then
redirects back to its home view.

per-pr context (what changed, what's risky) goes in the pr description as a ## What to test note. skip it and tik-test plans from the diff alone.

---
signin-button: Preview Sign In
---

# acme
…

how it works

                    ┌──────────────┐
                    │  tiktest.md  │◄── pr body, config, optional inline goal list
                    └──────┬───────┘
                           ▼
     ┌─────────────────────────────────────────────┐
     │ 1. plan           1-3 high-level goals      │  ← claude generates
     │ 2. drive          agent runs playwright mcp │  ← records raw.webm + tool log
     │ 3. narrate        claude writes the script  │  ← intro + beats + outro, one call
     │ 4. voice          openai tts (rotating)     │  ← one wav per beat
     │ 5. trim           ffmpeg crops idle waits   │  ← login spinners → 0.3s
     │ 6. compose        remotion overlays         │  ← pan/zoom, captions, clicks, audio
     │ 7. checklist      claude summarises 6-10    │  ← ai-checks list shown on outro
     │ 8. publish        github release + comment  │  ← + formal pr review (approve/reject)
     └─────────────────────────────────────────────┘
                           ▼
                  `highlights.mp4` + `preview.gif`

install

# macos
brew install ffmpeg node && gh auth login
git clone https://github.com/marcushyett/tik-test && cd tik-test
npm install && npx playwright install chromium && npm run build

# ubuntu / github action runner
sudo apt-get install -y ffmpeg fonts-dejavu
npm install && npx playwright install chromium --with-deps && npm run build

quickstart

# 1. local app
python3 -m http.server 4173 --directory examples/todo-app &
node dist/cli.js run --config examples/todo-app/tiktest.md --quick

# 2. github pr
node dist/cli.js pr https://github.com/owner/repo/pull/42

# 3. claude code plugin (after `/plugin install tiktest@tiktest`)
/tiktest:run            # video walkthrough on Desktop + checklist
/tiktest:quick          # checklist only, no video

npm install -g tik-test                  # cli the plugin shells out to
npx playwright install chromium          # browser the agent drives
brew install ffmpeg                      # or `sudo apt install ffmpeg` on linux
claude setup-token                       # sign claude cli in

/plugin marketplace add marcushyett/tik-test
/plugin install tiktest@tiktest
/tiktest:setup                           # scaffolds tiktest.md for your project

github action

copy a template from templates/workflows/ into .github/workflows/tik-test.yml. three options:

• local-dev.yml — npm run dev inside the runner. spas, static sites, next.js with mocked apis.
• vercel-preview.yml — drive your per-pr vercel preview, including the automation-bypass plumbing.
• staging-with-services.yml — boots postgres + redis service containers, runs migrations + seeds, then starts the app. rails / django / next.js + prisma.

minimal hand-written yaml if you'd rather wire it up by hand:

name: tik-test review
on:
  deployment_status:
  pull_request:
  workflow_dispatch:
    inputs:
      pr_number: { description: PR number, required: true }

permissions: { contents: write, pull-requests: write, id-token: write }

jobs:
  review:
    if: |
      github.event_name == 'workflow_dispatch' ||
      github.event_name == 'pull_request' ||
      (github.event_name == 'deployment_status' && github.event.deployment_status.state == 'success')
    runs-on: ubuntu-latest
    timeout-minutes: 25
    steps:
      - uses: actions/checkout@v4
      - uses: marcushyett/tik-test@v1
        with:
          claude-code-oauth-token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
          openai-api-key:          ${{ secrets.OPENAI_API_KEY }}            # optional
          vercel-bypass-secret:    ${{ secrets.VERCEL_AUTOMATION_BYPASS_SECRET }}  # optional
          pr-number:               ${{ github.event.inputs.pr_number }}     # workflow_dispatch only

the action installs node + ffmpeg + playwright, builds tik-test, auto-detects the pr number and preview url, runs the review, posts back.

in the wild

the demo above is the bundled taskpad app. agent caught two planted bugs (case-sensitive search, priority-sort reversed) and posted a request-changes review.

tiktest.dev is a tiktok-style web viewer for your tik-test videos. github is the backend, i store nothing. self-host with node dist/cli.js view against your local runs/.

{
  "name": "Theater mode",
  "summary": "Verify the new full-screen viewer keeps keyboard shortcuts working.",
  "startUrl": "https://acme-pr-42.vercel.app",
  "goals": [
    { "id": "open-theater", "intent": "Open the Inspiration grid and click Theater on any card.", "shortLabel": "Open Theater" },
    { "id": "kbd-shortcuts", "intent": "While in Theater mode, press Down, S, then Esc, verifying each works.", "shortLabel": "Keyboard nav", "importance": "high" }
  ]
}

advanced

node dist/cli.js config prints every knob with its current value, default, and risk of changing. same data as below.

contributing

see CONTRIBUTING.md. i'm opinionated about my workflow but open to feedback — happy to redesign anything that doesn't fit yours.

npm run build && OPENAI_API_KEY=... node dist/cli.js run --config examples/todo-app/tiktest.md --quick

license

mit. see LICENSE.