crawl4ai/docs/examples/c4a_script/tutorial/README.md

C4A-Script Interactive Tutorial

Welcome to the C4A-Script Interactive Tutorial! This hands-on tutorial teaches you how to write web automation scripts using C4A-Script, a domain-specific language for Crawl4AI.

🚀 Quick Start

1. Start the Tutorial Server

cd docs/examples/c4a_script/tutorial
python server.py

Then open your browser to: http://localhost:8080

2. Try Your First Script

# Basic interaction
GO playground/
WAIT `body` 2
IF (EXISTS `.cookie-banner`) THEN CLICK `.accept`
CLICK `#start-tutorial`

📚 What You'll Learn

Basic Commands

• Navigation: GO url
• Waiting: WAIT selector timeout or WAIT seconds
• Clicking: CLICK selector
• Typing: TYPE "text"
• Scrolling: SCROLL DOWN/UP amount

Control Flow

• Conditionals: IF (condition) THEN action
• Loops: REPEAT (action, condition)
• Procedures: Define reusable command sequences

Advanced Features

• JavaScript evaluation: EVAL code
• Variables: SET name = "value"
• Complex selectors: CSS selectors in backticks

🎮 Interactive Playground Features

The tutorial includes a fully interactive web app with:

1. Authentication System

• Login form with validation
• Session management
• Protected content

2. Dynamic Content

• Infinite scroll products
• Pagination controls
• Load more buttons

3. Complex Forms

• Multi-step wizards
• Dynamic field visibility
• Form validation

4. Interactive Elements

• Tabs and accordions
• Modals and popups
• Expandable content

5. Data Tables

• Sortable columns
• Search functionality
• Export options

🛠️ Tutorial Features

Live Code Editor

• Syntax highlighting
• Real-time compilation
• Error messages with suggestions

JavaScript Output Viewer

• See generated JavaScript code
• Edit and test JS directly
• Understand the compilation

Visual Execution

• Step-by-step progress
• Element highlighting
• Console output

Example Scripts

Load pre-written examples demonstrating:

• Cookie banner handling
• Login workflows
• Infinite scroll automation
• Multi-step form completion
• Complex interaction sequences

📖 Tutorial Sections

1. Getting Started

Learn basic commands and syntax:

GO https://example.com
WAIT `.content` 5
CLICK `.button`

2. Handling Dynamic Content

Master waiting strategies and conditionals:

IF (EXISTS `.popup`) THEN CLICK `.close`
WAIT `.results` 10

3. Form Automation

Fill and submit forms:

CLICK `#email`
TYPE "user@example.com"
CLICK `button[type="submit"]`

4. Advanced Workflows

Build complex automation flows:

PROC login
  CLICK `#username`
  TYPE $username
  CLICK `#password`
  TYPE $password
  CLICK `#login-btn`
ENDPROC

SET username = "demo"
SET password = "pass123"
login

🎯 Practice Challenges

Challenge 1: Cookie & Popups

Handle the cookie banner and newsletter popup that appear on page load.

Challenge 2: Complete Login

Successfully log into the application using the demo credentials.

Challenge 3: Load All Products

Use infinite scroll to load all 100 products in the catalog.

Challenge 4: Multi-step Survey

Complete the entire multi-step survey form.

Challenge 5: Full Workflow

Create a script that logs in, browses products, and exports data.

💡 Tips & Tricks

1. Use Specific Selectors

# Good - specific
CLICK `button.submit-order`

# Bad - too generic
CLICK `button`

2. Always Handle Popups

# Check for common popups
IF (EXISTS `.cookie-banner`) THEN CLICK `.accept`
IF (EXISTS `.newsletter-modal`) THEN CLICK `.close`

3. Add Appropriate Waits

# Wait for elements before interacting
WAIT `.form` 5
CLICK `#submit`

4. Use Procedures for Reusability

PROC handle_popups
  IF (EXISTS `.popup`) THEN CLICK `.close`
  IF (EXISTS `.cookie-banner`) THEN CLICK `.accept`
ENDPROC

# Use anywhere
handle_popups

🔧 Troubleshooting

Common Issues

1. "Element not found"

   • Add a WAIT before clicking
   • Check selector specificity
   • Verify element exists with IF

2. "Timeout waiting for selector"

   • Increase timeout value
   • Check if element is dynamically loaded
   • Verify selector is correct

3. "Missing THEN keyword"

   • All IF statements need THEN
   • Format: IF (condition) THEN action

🚀 Using with Crawl4AI

Once you've mastered C4A-Script in the tutorial, use it with Crawl4AI:

from crawl4ai import AsyncWebCrawler, CrawlerRunConfig

config = CrawlerRunConfig(
    url="https://example.com",
    c4a_script="""
    WAIT `.content` 5
    IF (EXISTS `.load-more`) THEN CLICK `.load-more`
    WAIT `.new-content` 3
    """
)

async with AsyncWebCrawler() as crawler:
    result = await crawler.arun(config=config)

📝 Example Scripts

Check the scripts/ folder for complete examples:

• 01-basic-interaction.c4a - Getting started
• 02-login-flow.c4a - Authentication
• 03-infinite-scroll.c4a - Dynamic content
• 04-multi-step-form.c4a - Complex forms
• 05-complex-workflow.c4a - Full automation

🤝 Contributing

Found a bug or have a suggestion? Please open an issue on GitHub!

---

Happy automating with C4A-Script! 🎉