Design Document: Automated Gym Reservation Bot Using Selenium and Python

A good design document should provide a clear problem statement, an overall high‑level design, and detailed specifications for each component.

This translation of a short English article explains how a Google engineer writes design docs, using a real project that automates gym reservation during the pandemic. The author emphasizes that documentation at Google is used for problem discussion, knowledge organization, and as a reliable information source.

Problem Description

During the COVID‑19 pandemic, a gym needed to limit the number of on‑site members, requiring users to book a slot online at least two days in advance, starting at midnight. The author found the reservation process inconvenient and ethically questionable, so they decided to write a program to automate the booking.

Requirements

Automatically book a gym slot two days in advance at midnight.

The program must run without manual interaction, be fault‑tolerant, and retry intelligently.

It should run on a Mac.

Users can specify username, password, sport, date, and time via command‑line arguments.

Out of Scope

Booking only 1‑2 days in advance or same‑day bookings.

Handling OS or network failures.

Operating after the reservation server shuts down.

Adapting to HTML structure changes.

Overview Design

The solution uses browser automation (Selenium) rather than pure HTTP request simulation because it provides a real browser instance for easier debugging, handles JavaScript‑driven pages, and offers better visibility of what the program does.

The system consists of Selenium (controlled via Python) to drive Firefox, and a helper tool caffeinate to prevent the Mac from sleeping until the script finishes.

Detailed Design

User Input : Username, password, date, time, and sport are passed as command‑line arguments.

Retry Logic : The script catches all exceptions and retries up to 100 times until a reservation succeeds, detecting success by confirming a specific DOM element.

Browser Choice : Firefox was selected after evaluating Chrome, Safari, and Chrome, due to driver availability and fewer extra steps.

Logging : Each loop logs the action performed and the expected condition, making debugging straightforward.

Preventing Sleep : The script launches caffeinate as a subprocess to keep the OS awake:

subprocess.Popen(['caffeinate', '-d', '-w', '%d' % os.getpid()])

Element Location : Uses Selenium’s find_element_by_xpath to locate buttons and inputs, preferring internal text over class names for stability.

Page Load Waiting : After each request, the script waits 2‑5 seconds (or up to 120 seconds) for elements to become clickable using WebDriverWait:

book_btn = WebDriverWait(driver, 120).until(EC.element_to_be_clickable((By.XPATH, "//button[@ng-reflect-router-link='/Appointments']")))

If the button does not appear within the timeout, an exception is raised.

Additional Implementation Details

Selecting the correct date requires handling calendar cells with class cal-in-month and adjusting the month when the target date falls in the next month.

Operation Flow

To book the small pool on April 14, run the script on April 11 at any time:

python book.py --username xxxxxx --password xxxxxx --day 14 --time '5:00 PM' --sport small_pool

The script wakes every second to check the time, uses caffeinate to stay awake, launches Firefox at midnight on April 12, performs the reservation, then exits, allowing the OS to sleep normally.

Interesting Fact

Booking slots are highly competitive; only six slots are available per time slot, and reservations typically finish within the first minute, making early‑morning bookings practically impossible.