BAMC - Advanced Documentation

This document provides a detailed breakdown of the argument types for each action and feature in the BAMC Language.

Actions

Command Syntax Example Description Argument Types
add-header add-header "DNT" "1" Adds an HTTP Header for the current request.
  • Argument 1 (Header Name): string (e.g., "DNT")
  • Argument 2 (Header Value): string (e.g., "1")
add-headers add-headers {"header-name1": "header-value1", ...} Adds multiple HTTP Headers for the current request via a JSON Object.
  • Argument 1 (Headers): JSON Object (Key-value pairs where keys are header names (string) and values are header values (string))
browser browser "chrome" Specifies the browser type. This MUST be the first valid line of the file. If not supplied, defaults to a Firefox instance or user agent.
  • Argument 1 (Browser Type): string ("chrome" or "firefox")
click click "selector" Clicks the specified button element. Supports ID, NAME, TAG NAME, and XPATH selectors.
  • Argument 1 (Selector): string (A valid ID, NAME, TAG NAME, or XPATH selector for the element to click)
click-exp click-exp 'css-selector.item_element' Alternative to click; use this if click is causing issues. Supports CSS SELECTOR.
  • Argument 1 (CSS Selector): string (A valid CSS selector for the element to click)
end-javascript end-javascript Instructs the parser that the end of a JavaScript code block was reached. An error will be thrown if end-javascript is not found within the file (when a start-javascript is present). No arguments.
fill-text fill-text "selector" "Value you want to include" Assigns the specified value to the selected element.
  • Argument 1 (Selector): string (A valid selector for the input element)
  • Argument 2 (Value): string (The text value to assign to the element)
fill-text-exp fill-text-exp "selector" "Value you want to include" More advanced version of fill-text.
  • Argument 1 (Selector): string (A valid selector for the input element)
  • Argument 2 (Value): string (The text value to assign to the element)
get-text get-text "selector" Gets the text for a specified element. Supports ID, NAME, TAG NAME, and XPATH selectors.
  • Argument 1 (Selector): string (A valid ID, NAME, TAG NAME, or XPATH selector for the element)
save-as-html save-as-html "filename.html" Saves the current page's HTML to a file with the specified name.
  • Argument 1 (File Name): string (The path and name of the HTML file to save, e.g., "output.html")
save-as-html-exp save-as-html-exp "filename.html" Saves the current page's HTML to a file with the specified name but uses different logic; use this if save-as-html doesn't fit your needs.
  • Argument 1 (File Name): string (The path and name of the HTML file to save)
select-option select-option "selector" 2 Selects an <option> from a <select> dropdown menu. Currently only supports <select><option></option></select>.
  • Argument 1 (Selector): string (A valid selector for the <select> element)
  • Argument 2 (Option Number): integer (The 0-based or 1-based index of the option to select, depending on implementation details; 2 typically means the 3rd item if 0-based, or 2nd if 1-based. Clarification needed for specific implementation.)
select-element select-element "selector" Selects the element associated with the provided selector (if found). This currently works but, there's no logic to access the selected element; this should only be done if you're manually editing the compiled Python script.
  • Argument 1 (Selector): string (A valid selector for the element)
set-custom-useragent set-custom-useragent "Mozilla/5.0 (...)" Sets a custom user agent for the current script.
  • Argument 1 (User Agent String): string (The full user agent string to set)
start-javascript start-javascript Instructs the parser to read all following lines as a .js code block, until end-javascript is found; Will throw an error if end-javascript is not found within the file. No arguments.
take-screenshot take-screenshot "filename.png" Takes a screenshot of the browser after executing the previous line. It's recommended to add a "wait-for-seconds" command before executing this.
  • Argument 1 (File Name): string (The path and name of the PNG file to save, e.g., "screenshot.png")
visit visit "https://url-to-visit.com/page.html" Visits a specified URL.
  • Argument 1 (URL): string (A valid URL string, including protocol like "https://")
wait-for-seconds wait-for-seconds 1 Waits for the specified number of seconds before continuing. Supports decimals.
  • Argument 1 (Seconds): number (The duration to wait, can be an integer or a floating-point number, e.g., 1 or 0.2)

Features

Command Syntax Example Description Argument Types
async feature "async" This indicates to the compiler you want to create an asynchronous script. This should not be done unless you have experience using async functions in Python. Currently not supported, will throw an error if you use. No arguments for the feature declaration itself.
bypass-cloudflare feature "bypass-cloudflare" Instructs the browser to use a more advanced approach to bypass Cloudflare. Currently not supported, will throw an error if you use. No arguments for the feature declaration itself.
disable-pycache feature "disable-pycache" Instructs the compiler to disable the writing of the __pycache__ directory. This directory is written by Visual Studio Code and contains .pyc files. No arguments for the feature declaration itself.
use-http-proxy feature "use-http-proxy" "USER:PASS@IP:PORT" Uses the entered HTTP proxy for the session. Use "NULL:NULL@IP:PORT" if no user:pass authentication is required.
  • Argument 1 (Proxy String): string (Format: "USER:PASS@IP:PORT". Use "NULL:NULL@IP:PORT" for no authentication.)
use-https-proxy feature "use-https-proxy" "USER:PASS@IP:PORT" Uses the entered HTTPS proxy for the session. Use "NULL:NULL@IP:PORT" if no user:pass authentication is required.
  • Argument 1 (Proxy String): string (Format: "USER:PASS@IP:PORT". Use "NULL:NULL@IP:PORT" for no authentication.)
use-socks4-proxy feature "use-socks4-proxy" "USER:PASS@IP:PORT" Uses the entered SOCKS4 proxy for the session. Use feature "use-socks4-proxy" "NULL:NULL@IP:PORT" if no user:pass authentication is required.
  • Argument 1 (Proxy String): string (Format: "USER:PASS@IP:PORT". Use "NULL:NULL@IP:PORT" for no authentication.)
use-socks5-proxy feature "use-socks5-proxy" "USER:PASS@IP:PORT" Uses the entered SOCKS5 proxy for the session. Use feature "use-socks5-proxy" "NULL:NULL@IP:PORT" if no user:pass authentication is required.
  • Argument 1 (Proxy String): string (Format: "USER:PASS@IP:PORT". Use "NULL:NULL@IP:PORT" for no authentication.)

Selectors

For a tutorial on how to find selectors, please click here

Selector Type Description Example
ID Selector Selects an element by its unique id attribute. "myElementId" (for <div id="myElementId">)
NAME Selector Selects an element by its name attribute, commonly used for form elements. "username" (for <input name="username">)
TAG NAME Selector Selects all elements with a specific HTML tag name. "button" (for all <button> elements)
XPATH Selector Selects elements using an XML Path Language (XPath) expression, allowing for complex selections. "//div[@class='container']/p[2]"
CSS Selector Selects elements using Cascading Style Sheets (CSS) selectors, offering a flexible way to target elements based on their attributes, classes, IDs, and relationships. "div.product-item > h3.title"

Using SelectorGadget

SelectorGadget is a browser extension that makes it easy to find the correct CSS selector for any element on a web page. This is incredibly useful when you need to interact with specific elements using commands like click-exp or fill-text-exp.

Installation

  1. Install the Extension: Search for "SelectorGadget" in your browser's extension store (e.g., Chrome Web Store, Firefox Add-ons). Install it.
  2. Pin to Toolbar (Optional but Recommended): Once installed, you might want to pin it to your browser's toolbar for quick access.

How to Use

Follow these steps to find a CSS selector using SelectorGadget:

  1. Activate SelectorGadget: Navigate to the web page you want to inspect. Click on the SelectorGadget icon in your browser's toolbar. A yellow bar will appear at the bottom of the screen.
  2. Select Desired Elements (Green): Click on the element you want to select. SelectorGadget will highlight it in green and attempt to find a CSS selector that matches it. It will also highlight other elements that match the same selector.
  3. Deselect Unwanted Elements (Red): If SelectorGadget highlights elements you *don't* want to select (they will also be green), click on them. They will turn red, and SelectorGadget will refine the CSS selector to exclude them.
  4. Select More Elements (Green): If there are other elements you *do* want to select that are not currently highlighted, click on them. They will turn green, and SelectorGadget will adjust the CSS selector to include them.
  5. Copy the Selector: The yellow bar at the bottom will display the generated CSS selector. Once you are satisfied that only the desired elements are highlighted in green, copy the selector from this bar.
  6. Test the Selector: (Optional but recommended) You can paste the copied selector into your browser's developer console (F12, then go to the Console tab) and use document.querySelectorAll('your-selector-here') to see which elements it selects.

This CSS selector can now be used in your BAMC script with commands that support CSS selectors, such as click-exp or fill-text-exp.