PHPackages                             spatie/pest-plugin-test-time - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Testing & Quality](/categories/testing)
4. /
5. spatie/pest-plugin-test-time

ActiveLibrary[Testing & Quality](/categories/testing)

spatie/pest-plugin-test-time
============================

A Pest plugin to control the flow of time

2.2.1(8mo ago)491.5M—8.9%820MITPHPPHP ^8.1CI passing

Since Jul 17Pushed 8mo ago2 watchersCompare

[ Source](https://github.com/spatie/pest-plugin-test-time)[ Packagist](https://packagist.org/packages/spatie/pest-plugin-test-time)[ Docs](https://github.com/spatie/pest-plugin-test-time)[ GitHub Sponsors](https://github.com/spatie)[ RSS](/packages/spatie-pest-plugin-test-time/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (9)Dependencies (4)Versions (10)Used By (20)

A Pest plugin to control the flow of time
=========================================

[](#a-pest-plugin-to-control-the-flow-of-time)

[![Latest Version on Packagist](https://camo.githubusercontent.com/9eddcfcef3269d9748418c7e29d133f0c8e84bc6ef068b86d015760f43adb182/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f7370617469652f706573742d706c7567696e2d746573742d74696d652e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/spatie/pest-plugin-test-time)[![Tests](https://github.com/spatie/pest-plugin-test-time/actions/workflows/run-tests.yml/badge.svg)](https://github.com/spatie/pest-plugin-test-time/actions/workflows/run-tests.yml)[![Total Downloads](https://camo.githubusercontent.com/57d86e7135abc02266fc51e2b8f373b9aa140bca46b35c45a039e886b28de639/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f7370617469652f706573742d706c7567696e2d746573742d74696d652e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/spatie/pest-plugin-test-time)

This [Pest](https://pestphp.com) plugin offers a function `testTime` that allows you to freeze and manipulate the current time in your tests.

```
use function Spatie\PestPluginTestTime\testTime;

testTime()->freeze(); // time will not change anymore

testTime()->addMinute(); // move time forward one minute
```

It also contains a custom expectation called `toBeCarbon` to easily check the values of `Carbon` instances.

```
$carbon = Carbon::createFromFormat('Y-m-d H:i:s', '2022-05-31 01:02:03');

// make an expectation on the whole date, including time
expect($carbon)->toBeCarbon('2022-05-31 01:02:03');

// make an expectation on only the date part
expect($carbon)->toBeCarbon('2022-05-31');

// explicitly pass in a format
expect($carbon)->toBeCarbon('2022', 'Y');
```

Support us
----------

[](#support-us)

[![](https://camo.githubusercontent.com/fd76ce505d2a5894d5a9ef213b2887c29f364e51d37dc69df7aa8c28de1514e2/68747470733a2f2f6769746875622d6164732e73332e65752d63656e7472616c2d312e616d617a6f6e6177732e636f6d2f706573742d706c7567696e2d746573742d74696d652e6a70673f743d31)](https://spatie.be/github-ad-click/pest-plugin-test-time)

We invest a lot of resources into creating [best in class open source packages](https://spatie.be/open-source). You can support us by [buying one of our paid products](https://spatie.be/open-source/support-us).

We highly appreciate you sending us a postcard from your hometown, mentioning which of our package(s) you are using. You'll find our address on [our contact page](https://spatie.be/about-us). We publish all received postcards on [our virtual postcard wall](https://spatie.be/open-source/postcards).

Requirements
------------

[](#requirements)

This package is a wrapper around [Carbon](https://carbon.nesbot.com/docs/)'s `setTestNow()` function. Therefore, you can only use this Pest plugin only in projects that use Carbon.

Installation
------------

[](#installation)

You can install the package via composer:

```
composer require spatie/pest-plugin-test-time --dev
```

Usage
-----

[](#usage)

You can call `freeze` on the `testTime` function to freeze the current time.

```
use Carbon\Carbon;
use function Spatie\PestPluginTestTime\testTime;

testTime()->freeze(); // the current time will not change anymore

Carbon::now(); // returns the time

sleep(2);

Carbon::now(); // will return the same time as above
```

### Freezing at a specific point in time

[](#freezing-at-a-specific-point-in-time)

You can also freeze the time at a specific point by passing the time in format `Y-m-d H:i:s`.

```
testTime()->freeze('2021-01-02 12:34:56');

\Carbon\Carbon::now()->format('Y-m-d H:i:s') // returns '2021-01-02 12:34:56';
```

### Changing the time

[](#changing-the-time)

You can change the time, by calling any of the `add` and `sub` functions that are available on `Carbon`.

```
testTime()->freeze('2021-01-02 12:34:56');

testTime()->addHour(); // time is now at '2021-01-02 13:34:56'

// you can even chain method calls
testTime()->subMinute()->addSeconds(2); // time is now at '2021-01-02 13:33:58'
```

### Expecting a Carbon value

[](#expecting-a-carbon-value)

This package offers a custom expectation called `toBeCarbon` to easily check the value of a `Carbon` instance.

```
$carbon = Carbon::createFromFormat('Y-m-d H:i:s', '2022-05-31 01:02:03');

// make an expectation on the whole date, including time
expect($carbon)->toBeCarbon('2022-05-31 01:02:03');

// make an expectation on only the date part
expect($carbon)->toBeCarbon('2022-05-31');

// explicitly pass in a format
expect($carbon)->toBeCarbon('2022', 'Y');
```

Testing
-------

[](#testing)

```
composer test
```

Changelog
---------

[](#changelog)

Please see [CHANGELOG](CHANGELOG.md) for more information on what has changed recently.

Contributing
------------

[](#contributing)

Please see [CONTRIBUTING](https://github.com/spatie/.github/blob/main/CONTRIBUTING.md) for details.

Security Vulnerabilities
------------------------

[](#security-vulnerabilities)

Please review [our security policy](../../security/policy) on how to report security vulnerabilities.

Credits
-------

[](#credits)

- [Freek Van der Herten](https://github.com/freekmurze)
- [All Contributors](../../contributors)

License
-------

[](#license)

The MIT License (MIT). Please see [License File](LICENSE.md) for more information.

###  Health Score

56

—

FairBetter than 98% of packages

Maintenance59

Moderate activity, may be stable

Popularity53

Moderate usage in the ecosystem

Community34

Small or concentrated contributor base

Maturity66

Established project with proven stability

 Bus Factor1

Top contributor holds 75% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~187 days

Recently: every ~294 days

Total

9

Last Release

267d ago

Major Versions

0.0.2 → 1.0.02021-07-25

1.1.1 → 2.0.02023-03-21

PHP version history (2 changes)0.0.1PHP ^8.0

2.0.0PHP ^8.1

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/7535935?v=4)[Spatie](/maintainers/spatie)[@spatie](https://github.com/spatie)

---

Top Contributors

[![freekmurze](https://avatars.githubusercontent.com/u/483853?v=4)](https://github.com/freekmurze "freekmurze (42 commits)")[![AdrianMrn](https://avatars.githubusercontent.com/u/12762044?v=4)](https://github.com/AdrianMrn "AdrianMrn (5 commits)")[![riasvdv](https://avatars.githubusercontent.com/u/3626559?v=4)](https://github.com/riasvdv "riasvdv (3 commits)")[![AlexVanderbist](https://avatars.githubusercontent.com/u/6287961?v=4)](https://github.com/AlexVanderbist "AlexVanderbist (2 commits)")[![gpibarra](https://avatars.githubusercontent.com/u/21188012?v=4)](https://github.com/gpibarra "gpibarra (2 commits)")[![chengkangzai](https://avatars.githubusercontent.com/u/43839286?v=4)](https://github.com/chengkangzai "chengkangzai (1 commits)")[![mihaileu](https://avatars.githubusercontent.com/u/54336101?v=4)](https://github.com/mihaileu "mihaileu (1 commits)")

---

Tags

carbonpestphptestingtimespatiepest-plugin-test-time

### Embed Badge

![Health badge](/badges/spatie-pest-plugin-test-time/health.svg)

```
[![Health](https://phpackages.com/badges/spatie-pest-plugin-test-time/health.svg)](https://phpackages.com/packages/spatie-pest-plugin-test-time)
```

###  Alternatives

[spatie/temporary-directory

Easily create, use and destroy temporary directories

96889.9M206](/packages/spatie-temporary-directory)[spatie/laravel-sitemap

Create and generate sitemaps with ease

2.6k14.6M107](/packages/spatie-laravel-sitemap)[spatie/phpunit-snapshot-assertions

Snapshot testing with PHPUnit

69617.9M510](/packages/spatie-phpunit-snapshot-assertions)[spatie/laravel-responsecache

Speed up a Laravel application by caching the entire response

2.8k8.2M51](/packages/spatie-laravel-responsecache)[spatie/phpunit-watcher

Automatically rerun PHPUnit tests when source code changes

8839.2M475](/packages/spatie-phpunit-watcher)[spatie/laravel-honeypot

Preventing spam submitted through forms

1.6k6.0M60](/packages/spatie-laravel-honeypot)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)