►Congame
►4 The Congame Server
▼4.4 Congame Reference
►4.4.3 Bots
On this page:
bot?
make-bot
bot-stepper?
make-bot-stepper
4.4.3.1 Making Bots
model/  c
study->bot
4.4.3.2 Bot Actions
run-bot
current-page
completer
continuer
click
click-all
type-all
wait-for
show
find
find-all
element-find
element-find-all
4.4.3.3 Running Bots From Studies
spawn-bot
    contents    up   
4.4.3 Bots🔗

 (require congame/components/bot) package: congame-core

Bots are scriptable automatons that traverse a study according to a bot model. A bot is made up of one or more bot steppers and a bot model is a mapping from locations in a study to bot behaviors. A bot stepper is an arbitrary procedure associated with a step that determines what the bot does when it reaches that step.

procedure

(bot? v) → boolean?

  v : any/c
Returns #t when v is a bot.

procedure

(make-bot step ...+) → bot?

  step : (or/c bot? bot-stepper?)
Returns a bot with the given steppers.

This is a primitive procedure used to implement study->bot. You should use study->bot unless you really know what you’re doing.

procedure

(bot-stepper? v) → boolean?

  v : any/c
Returns #t when v is a bot stepper.

procedure

(make-bot-stepper step-id action) → bot-stepper?

  step-id : symbol?
  action : (-> any/c)
Returns a bot stepper for the given step-id and action combination.

As with make-bot, you shouldn’t normally need this procedure.

4.4.3.1 Making Bots🔗

 (require congame/components/bot-maker)
  package: congame-core

value

model/c : (-> (listof symbol?) procedure? any)

The contract for bot models.

procedure

(study->bot s) → (-> model/c bot?)

  s : study?
Returns a procedure that generates a bot suitable for running against s. The returned procedure takes a bot model as input.

The model is called every time the bot lands on a step with the path to that step, represented as a list of symbols, and the default bot action for that step. The model can then decide whether to call the bot action or perform its own actions, or both.

At every step, the model can access instance and participant data through any study variables that it has access to. Within the dynamic extent of a model invocation, the current participant is the bot currently running the model.

4.4.3.2 Bot Actions🔗

 (require (submod congame/components/bot actions))

procedure

(run-bot b    
  #:study-url url    
  #:username username    
  #:password password    
  [#:delay delay    
  #:browser browser    
  #:headless? headless?    
  #:port port]) → void?
  b : bot?
  url : string?
  username : string?
  password : string?
  delay : real? = 0
  browser : (or/c #f browser?) = #f
  headless? : boolean? = #t
  port : (or/c #f (integer-in 0 65535)) = #f
Runs bot b against the study at url with the given username and password.

parameter

(current-page) → (or/c #f page?)

(current-page page) → void?
  page : (or/c #f page?)
Within a bot action, this represents the current page.

procedure

(completer) → void?

A bot action that stops the bot when run.

procedure

(continuer) → void?

A bot action that continues to the next step when run.

procedure

(click id) → void?

  id : symbol?
A bot action that clicks on the widget id when run.

procedure

(click-all elts) → void?

  elts : (listof element?)
Clicks every element in elts.

procedure

(type-all elts&text) → void?

  elts&text : (hash/c element? string?)
Types into every element key of elts&text the associated string.

procedure

(wait-for selector) → void?

  selector : string?
Waits until an element with the given selector appears on the page.

procedure

(show selector) → void?

  selector : string?
Sets the display style of the first element that matches selector to block.

procedure

(find selector) → (or/c #f element?)

  selector : string?
Returns the first element that matches selector.

procedure

(find-all selector) → (listof element?)

  selector : string?
Returns all the elements that match selector.

procedure

(element-find elt selector) → (or/c #f element?)

  elt : element?
  selector : string?
Returns the first child of elt that matches selector.

procedure

(element-find-all elt selector) → (listof element?)

  elt : element?
  selector : string?
Returns all the children of elt that match selector.

4.4.3.3 Running Bots From Studies🔗

 (require congame-web/components/study-bot)
  package: congame-web

procedure

(spawn-bot b) → void?

  b : bot?
Creates a new user, adds it to the current study instance as a participant and launches the bot b in the background. Does not wait for the bot to finish before returning.

Raises an exception if called outside of a step.

    contents    up