Skip to main content

Time Freezing​

View as Markdown
EnterpriseSelf-HostedDedicated

Why Time Freezing? ❄️​

While making tests, time-sensitive objects like JWT tokens are a challenge as they expire, leading to test failures. This increases the maintenance effort of test suites and also impacts reliability.

What is Time Freezing? ⏳​

With Keploy Cloud users will be able to freeze/rollback the time in every test run, back to when the test case was recorded.

This allows developers to ensure time-sensitive objects don’t expire or change, making tests consistent and more reliable.

Usage 🛠️​

Running natively on Linux (or WSL) 🐧​

When Keploy runs natively on Linux — including inside WSL on Windows — simply add the --freezeTime flag when running your tests, like so:

keploy test -c "<appCmd>" --freezeTime

Voila! Your tests will now run with time freezing enabled.

Running natively on macOS or Windows 🍎💻​

Time freezing isn't supported when Keploy runs natively on macOS or Windows (outside WSL): even with --freezeTime, the application runs on the real clock.

To freeze time on these platforms, run your application with Docker as described in Running on Docker below, or run Keploy on Linux: in WSL on Windows, or in a Lima VM on macOS.

Running on Docker 🐳​

For Docker-based applications, you'll need to make a few adjustments to your Dockerfile to utilize this feature:

  1. First, check your system architecture
uname -a
  1. Download the appropriate time freeze agent for your architecture & set the LD_PRELOAD Environment Variable in your Dockerfile

For Golang(Go) Applications -​

Note: Time freezing works on every Go version that supports the faketime build tag, i.e. all currently supported Go releases. The mechanism is build-time (the -tags=faketime flag swaps Go's time package to read from a runtime agent file instead of the OS clock), so it's not tied to any specific Go version.

amd64/x86_64 🖥️​

# Download the time freeze agent
ADD https://keployenterprise.blob.core.windows.net/releases/latest/assets/go_freeze_time_amd64 /lib/keploy/go_freeze_time_amd64

# set suitable permissions
RUN chmod +x /lib/keploy/go_freeze_time_amd64

# run the binary
RUN /lib/keploy/go_freeze_time_amd64

# build your binary with fake time (during test mode)
RUN go build -tags=faketime <your_main_file>

OR

arm64/aarch64 📱​

# Download the time freeze agent

ADD https://keployenterprise.blob.core.windows.net/releases/latest/assets/go_freeze_time_arm64 /lib/keploy/go_freeze_time_arm64

# set suitable permissions
RUN chmod +x /lib/keploy/go_freeze_time_arm64

# run the binary
RUN /lib/keploy/go_freeze_time_arm64

# build your binary with fake time (during test mode)
RUN go build -tags=faketime <your_main_file>

  1. Only Add faketime tag to your build script during Test MODE

  2. Re-Build your Docker image.

  3. Now add the --freezeTime flag when running your tests with Keploy, like so:

keploy test -c "<appCmd>" --freezeTime

Voila! Your tests will now run with time freezing enabled.

For Node/Java/Python Applications -​

amd64/x86_64 🖥️​

# Download the time freeze agent
ADD https://keployenterprise.blob.core.windows.net/releases/latest/assets/freeze_time_amd64.so /lib/keploy/freeze_time_amd64.so

#set suitable permissions
RUN chmod +x /lib/keploy/freeze_time_amd64.so

# Set LD_PRELOAD environment variable to use freeze_time_amd64.so
ENV LD_PRELOAD=/lib/keploy/freeze_time_amd64.so

OR

arm64/aarch64 📱​

# Download the time freeze agent
ADD https://keployenterprise.blob.core.windows.net/releases/latest/assets/freeze_time_arm64.so /lib/keploy/freeze_time_arm64.so

#set suitable permissions
RUN chmod +x /lib/keploy/freeze_time_arm64.so

# Set LD_PRELOAD environment variable to use freeze_time_arm64.so
ENV LD_PRELOAD=/lib/keploy/freeze_time_arm64.so
  1. Re-Build your Docker image.
  2. Now add the --freezeTime flag when running your tests with Keploy, like so:
keploy test -c "<appCmd>" --freezeTime

Voila! Your tests will now run with time freezing enabled.