UI Test Generator

A responsive web app that scans publicly accessible websites for accessibility violations and usability issues. It combines specialized JavaScript libraries with the Gemini API to explain findings in plain English, generate contextual test scenarios, and export a downloadable PDF report.

Features

• Accessibility scanning via @axe-core/playwright
• Usability checks via Cheerio (missing alt text, unlabelled inputs, buttons with no text)
• Performance metrics via Playwright (DOMContentLoaded and full load time)
• Broken link detection on the submitted page via broken-link-checker
• AI enrichment via Gemini (plain-English explanations and generated test scenarios)
• PDF report export

Requirements

• Node.js 20+
• A Google Gemini API key

Setup

1. Install dependencies:

npm install

2. Install Playwright Chromium (required for accessibility scans):

npm run install:browsers

2. Configure environment variables:

cp .env.example .env.local

Add your Gemini API key to .env.local:

GEMINI_API_KEY=your_gemini_api_key_here

3. Start the development server:

npm run dev

Open http://localhost:3000 in your browser.

Usage

1. Enter a public http or https URL.
2. Click Scan.
3. Review accessibility, usability, and broken-link findings.
4. Read Gemini-generated explanations and test scenarios.
5. Click Download PDF Report to export results.

Deployment

This app uses Playwright and can take 30–120 seconds per scan. Deploy as a Docker container on a VM or web service (not a static site or serverless function).

Files included

• Dockerfile — multi-stage build with Chromium for accessibility scans
• .dockerignore — keeps the image lean
• render.yaml — optional Render Blueprint

Local Docker test

docker build -t ui-test-generator .
docker run --rm -p 3000:3000 -e GEMINI_API_KEY=your_key ui-test-generator

Open http://localhost:3000 and run a scan against https://example.com.

Deploy on Render

1. Push this repo to GitHub or GitLab.
2. In Render, choose New → Web Service and connect the repo.
3. Set Environment to Docker (Render auto-detects the Dockerfile).
4. Add environment variable GEMINI_API_KEY with your production key.
5. Use at least the Starter plan (512 MB); Standard (1 GB+) is recommended for Chromium.
6. Set Health Check Path to /.
7. Deploy.

Alternatively, use the Blueprint: New → Blueprint and point Render at this repo (uses render.yaml).

Deploy on Oracle Cloud (OCI)

Use an Always Free Ampere A1/A2 VM (recommended: 1+ OCPU, 2 GB+ RAM) running Ubuntu 22.04 or 24.04.

1. Create the VM

1. In Oracle Cloud, go to Compute → Instances → Create instance.
2. Choose Ubuntu and an Ampere A1/A2 Flex shape (or another VM with at least 1 GB RAM).
3. Assign a public IPv4 address and upload your SSH public key.
4. Create the instance.

2. Open network ports

On the instance's subnet Security List, add ingress rules:

Source CIDR	Protocol	Port	Purpose
Your IP/32	TCP	22	SSH
0.0.0.0/0	TCP	80	HTTP (optional, for HTTPS proxy)
0.0.0.0/0	TCP	443	HTTPS (optional)
0.0.0.0/0	TCP	3000	App (or restrict to your IP while testing)

3. Install Docker on the VM

ssh -i /path/to/your-private-key ubuntu@<PUBLIC_IP>

curl -fsSL https://get.docker.com | sudo sh
sudo usermod -aG docker $USER
newgrp docker

4. Clone and build

git clone https://github.com/<your-user>/ui-test-generator.git
cd ui-test-generator

docker build -t ui-test-generator .

The first build may take several minutes (Playwright and Chromium are installed in the image).

5. Run the container

docker run -d \
  --name ui-test-generator \
  --restart unless-stopped \
  -p 3000:3000 \
  -e GEMINI_API_KEY="your_gemini_key_here" \
  -e NODE_ENV=production \
  ui-test-generator

Verify:

docker ps
curl -s -o /dev/null -w "HTTP %{http_code}\n" http://localhost:3000

Open http://<PUBLIC_IP>:3000 in your browser.

6. Redeploy after code changes

cd ~/ui-test-generator
git pull
docker build -t ui-test-generator .
docker rm -f ui-test-generator
docker run -d \
  --name ui-test-generator \
  --restart unless-stopped \
  -p 3000:3000 \
  -e GEMINI_API_KEY="your_gemini_key_here" \
  -e NODE_ENV=production \
  ui-test-generator

Useful commands

docker logs -f ui-test-generator   # view logs
docker restart ui-test-generator   # restart the app

Optional: HTTPS with Caddy

Point a domain A record at your VM's public IP, install Caddy, and add a Caddyfile:

your-domain.com {
  reverse_proxy 127.0.0.1:3000
}

Then bind the container to localhost only (-p 127.0.0.1:3000:3000) and close public port 3000 in the security list.

Notes

• Serverless platforms like Vercel may hit cold-start and timeout limits because Playwright requires a full Chromium browser at runtime.
• Render free-tier services spin down after idle; the first request after sleep may be slow.
• On OCI, production Docker builds (next start) are typically faster than local pnpm dev because the VM runs an optimized build with dedicated resources.
• If scans fail around 60 seconds behind a reverse proxy, increase the proxy idle timeout to at least 120 seconds.

Tech stack

• Next.js 16
• Playwright + axe-core
• Cheerio
• broken-link-checker
• Google Gemini API
• jsPDF