1 files changed, 61 insertions, 33 deletions
diff --git a/docs/docs/testing.md b/docs/docs/testing.md
index dfca054..25aad8d 100644
--- a/docs/docs/testing.md
+++ b/docs/docs/testing.md
@@ -1,59 +1,87 @@
 # Testing
 
-The testing methods allow you to set a `DateTime` instance (real or mock) to be returned
-when a "now" instance is created.
-The provided instance will be returned specifically under the following conditions:
+Pendulum provides a few helpers to help you control the flow of time in your tests. Note that
+these helpers are only available if you opted in the `test` extra during [installation](#installation).
 
-* A call to the `now()` method, ex. `pendulum.now()`.
-* When the string "now" is passed to the `parse()` method, ex. `pendulum.parse('now')`
+!!!warning
+    If you are migrating from Pendulum 2, note that the `set_test_now()` and `test()`
+    helpers have been removed.
+
+
+## Relative time travel
+
+You can travel in time relatively to the current time
 
 ```python
 >>> import pendulum
 
-# Create testing datetime
->>> known = pendulum.datetime(2001, 5, 21, 12)
+>>> now = pendulum.now()
+>>> pendulum.travel(minutes=5)
+>>> pendulum.now().diff_for_humans(now)
+"5 minutes after"
+```
 
-# Set the mock
->>> pendulum.set_test_now(known)
+Note that once you've travelled in time the clock **keeps ticking**. If you prefer to stop the time completely
+you can use the `freeze` parameter:
 
->>> print(pendulum.now())
-'2001-05-21T12:00:00+00:00'
+```python
+>>> import pendulum
 
->>> print(pendulum.parse('now'))
-'2001-05-21T12:00:00+00:00'
+>>> now = pendulum.now()
+>>> pendulum.travel(minutes=5, freeze=True)
+>>> pendulum.now().diff_for_humans(now)
+"5 minutes after"  # This will stay like this indefinitely
+```
 
-# Clear the mock
->>> pendulum.set_test_now()
 
->>> print(pendulum.now())
-'2016-07-10T22:10:33.954851-05:00'
-```
+## Absolute time travel
 
-Related methods will also return values mocked according to the **now** instance.
+Sometimes, you may want to place yourself at a specific point in time.
+This is possible by using the `travel_to()` helper. This helper accepts a `DateTime` instance
+that represents the point in time where you want to travel to.
 
 ```python
->>> print(pendulum.today())
-'2001-05-21T00:00:00+00:00'
+>>> import pendulum
 
->>> print(pendulum.tomorrow())
-'2001-05-22T00:00:00+00:00'
+>>> pendulum.travel_to(pendulum.yesterday())
+```
 
->>> print(pendulum.yesterday())
-'2001-05-20T00:00:00+00:00'
+Similarly to `travel`, it's important to remember that, by default, the time keeps ticking so, if you prefer
+stopping the time, use the `freeze` parameter:
+
+```python
+>>> import pendulum
+
+>>> pendulum.travel_to(pendulum.yesterday(), freeze=True)
 ```
 
-If you don't want to manually clear the mock (or you are afraid of forgetting),
-you can use the provided `test()` contextmanager.
+## Travelling back to the present
+
+Using any of the travel helpers will keep you in the past, or future, until you decide
+to travel back to the present time. To do so, you may use the `travel_back()` helper.
 
 ```python
 >>> import pendulum
 
->>> known = pendulum.datetime(2001, 5, 21, 12)
+>>> now = pendulum.now()
+>>> pendulum.travel(minutes=5, freeze=True)
+>>> pendulum.now().diff_for_humans(now)
+"5 minutes after"
+>>> pendulum.travel_back()
+>>> pendulum.now().diff_for_humans(now)
+"a few seconds after"
+```
+
+However, it might be cumbersome to remember to travel back so, instead, you can use any of the helpers as a context
+manager:
 
->>> with pendulum.test(known):
->>>     print(pendulum.now())
-'2001-05-21T12:00:00+00:00'
+```python
+>>> import pendulum
 
->>> print(pendulum.now())
-'2016-07-10T22:10:33.954851-05:00'
+>>> now = pendulum.now()
+>>> with pendulum.travel(minutes=5, freeze=True):
+>>>     pendulum.now().diff_for_humans(now)
+"5 minutes after"
+>>> pendulum.now().diff_for_humans(now)
+"a few seconds after"
 ```