Tester votre intégration avec des horloges de simulation
Aperçu
Les horloges de simulation permettent de tester plus facilement votre intégration Billing et de s’assurer qu’elle se comporte comme prévu. Lorsque vous utilisez des horloges de simulation, vous simulez le passage du temps en mode test, ce qui fait que les ressources Billing telles que les abonnements changent d’état et déclenchent des événements webhook. Cela signifie par exemple que vous n’avez pas besoin d’attendre un an pour voir comment votre intégration gère un échec de paiement lors d’un renouvellement trimestriel ou annuel.
Voici quelques exemples d’actions que vous pouvez effectuer à l’aide des horloges de simulation :
- Tester des simulations complexes telles que la mise à niveau ou le changement de plans en milieu de cycle.
- Garantir que votre intégration traite correctement les webhooks relatifs aux cycles de facturation.
- Vérifier que votre application est capable de gérer les périodes d’essai gratuit.
- Générer et tester des planifications d’abonnement à plusieurs phases.
Fonctionnement des horloges de simulation
En règle générale, lorsque vous utilisez des horloges de simulation, vous passerez par les étapes suivantes : création d’une simulation, configuration du cas de test, avancement de l’heure/la date de la simulation et vérification de la façon dont votre intégration a géré ces changements.
Suivez ces étapes pour commencer à utiliser des horloges de simulation :
- Créer une horloge de simulation
- Configurer votre simulation test
- Avancer l’heure de l’horloge
- Surveiller et gérer les modifications
- Mettre la simulation à jour
- Supprimer l’horloge
Vous pouvez avancer la date et l’heure de l’horloge, surveiller les changements et mettre à jour la simulation autant que nécessaire pour tester différents cas.
Créer une horloge et définir la date et l'heure
Pour démarrer une simulation, créez une horloge et définissez sa date de départ fixe, c’est-à-dire le point de départ temporel de tous les abonnements associés à cette horloge. Vous pouvez la définir à une date ultérieure ou antérieure à la date actuelle pour tester différentes simulations, mais vous ne pouvez ensuite que la faire progresser dans le temps.
Configurer votre simulation
Ensuite, configurez le cas de test pour votre simulation. Vous devez d’abord créer un client, puis son abonnement.
Les objets Customer et Subscription sont associés à l’objet Clock que vous avez créé à la première étape. Dans le Dashboard, l’icône indique qu’un objet est associé à une horloge.
Avancer la date et l'heure de la simulation
Une fois que vous avez créé l’horloge de simulation et configuré votre cas de test, avancez la date et l’heure de l’horloge. La première fois, vous avancerez la date en partant de celle définie à la création de l’horloge. Vous pouvez ainsi observer le comportement de votre intégration lorsque des abonnements prennent fin, se renouvellent ou subissent des modifications (par exemple, le passage d’une période d’essai à un abonnement payant).
Les horloges de simulation ne peuvent avancer que de deux périodes à partir de leur date initiale. La durée de la période dépendra directement de la plus petite période d’abonnement associée à l’abonnement testé, qui elle-même correspond à la fréquence de récurrence du tarif. Par exemple, si l’horloge est associée à un abonnement mensuel, elle ne pourra être avancée que de deux mois. Les horloges qui ne sont pas associées à un calendrier d’abonnement peuvent être avancées de deux ans maximum à partir de la date initiale.
Surveiller et gérer les modifications
Après une requête réussie à l’API ou une opération dans le Dashboard et quelques secondes d’attente, l’horloge avance à la date et l’heure spécifiées. Pour savoir si l’état de l’horloge a changé, vous pouvez écouter les notifications d’événements à l’aide de webhooks ou interroger l’horloge. Le Dashboard reflète également les changements. Par exemple, vous pouvez accéder à la page Factures pour vérifier si une facture a été créée ou payée pour votre abonnement.
Si vous utilisez des webhooks, écoutez les notifications d’événements suivantes. Avant de passer au mode production, pensez à vérifier que votre intégration est capable de gérer les notifications d’événements de facturation autres que celles listées ci-dessous.
| Événement | Description |
|---|---|
test_helpers.test_clock.advancing | L’horloge a commencé à avancer mais n’a pas atteint la date et l’heure spécifiées. |
test_helpers.test_clock.ready | L’horloge a atteint à la date et à l’heure spécifiées. |
Pour interroger l’état de l’horloge, récupérez-le à l’aide de son ID pour examiner son status.
Mettre à jour la simulation
Vous pouvez continuer à apporter des changements à votre simulation et avancer l’horloge pour différentes simulations, par exemple :
- L’ajout d’un solde client.
- Le passage à un abonnement supérieur en cours de cycle.
- L’ajout de postes de facture ponctuels.
Après chaque mise à jour, surveillez à nouveau les changements. Réitérez l’opération au besoin pour votre cas de test.
Supprimer l'horloge
Les horloges de test sont automatiquement supprimées 30 jours après leur création, mais pour un environnement de test moins encombré, vous pouvez les effacer dès que votre test est terminé.
La suppression de l’horloge supprime également les clients qui y sont associés et annule leurs abonnements. Les horloges de simulation sont uniquement disponibles en mode test, vous ne risquez donc pas d’effacer des objets réels lors de la suppression d’une horloge.
Cas d'usage
Tester les renouvellements d’abonnements
Tout d’abord, suivez les étapes ci-après pour commencer à utiliser des horloges de simulation :
- Créer une horloge de simulation
- Configurer votre simulation test
- Avancer l’heure de l’horloge
- Surveiller et gérer les modifications
- Mettre la simulation à jour
Ensuite, vous pouvez tester certains renouvellements d’abonnements en utilisant les horloges de simulation. Imaginons que vous souhaitez tester si un abonnement à 50 EUR/mois se renouvelle correctement. Pour simuler cette situation en utilisant des horloges de simulation :
- Créez une nouvelle horloge de simulation et définissez son paramètre
frozen_timesur le 1er janvier. - Ajoutez un client et associez-y un moyen de paiement :
Suite à l’ajout d’un moyen de paiement pour le client, créez un abonnement pour le nouveau client à hauteur de 50 EUR/mois. Ce faisant, la facture de 50 EUR est payée automatiquement et l’abonnement bascule sur
active.Avancez la date au 1er février. Vous devriez constater qu’une facture de 50 EUR a été créée. Par défaut, la facture apparaît à l’état
draftpendant une heure.Avancez l’horloge d’une heure pour vérifier que la facture a bien été finalisée et payée automatiquement.
Tester des passages à un abonnement supérieur en cours de cycle avec des proratas
Tout d’abord, suivez les étapes ci-après pour commencer à utiliser des horloges de simulation :
- Créer une horloge de simulation
- Configurer votre simulation test
- Avancer l’heure de l’horloge
- Surveiller et gérer les modifications
- Mettre la simulation à jour
Ensuite, vous pouvez tester des calculs au prorata pour les clients qui mettent leurs plans à niveau au milieu d’un cycle de facturation. Imaginons que vous avez deux produits. Un produit est à 50 EUR/mois (‘basic plan‘) et l’autre est à 100 EUR/mois (‘premium plan‘). Dans ce cas, vous pourriez vouloir tester les calculs au prorata pour un client qui met à niveau son ‘basic plan‘ vers le ‘premium plan‘ au milieu d’un cycle de facturation. Pour simuler cette situation en utilisant les horloges de simulation :
- Créez une nouvelle horloge de simulation et définissez son paramètre
frozen_timesur le 1er janvier. - Créez un client et ajoutez son moyen de paiement. Ici, utilisez la carte de test .
- Créez un abonnement au ‘basic plan’ à 50 EUR/mois. Une fois terminé, vous remarquerez que la facture de 50 EUR/mois a été créée, finalisée et payée automatiquement.
- Avancez la date de deux semaines. Ici, nous définirons la date sur le 16 janvier.
- Passez à un abonnement supérieur ‘premium plan’ à 100 EUR/mois :
Après le passage à un abonnement supérieur, l’événement webhook customer.subscription.updated est créé.
Les postes de factures en attente sont aussi créés pour les proratas. Vous remarquerez un prorata négatif de -25 EUR pour la période non-consommée avec le ‘basic plan’, et un prorata positif de 50 EUR pour la consommation du ‘premium plan’ durant la moitié du mois restant. À ce stade, aucune facture n’a été générée.
Avancez la date de deux semaines. Dans ce cas, nous réglerons la date au 1er février. Vous remarquerez que l’abonnement a effectué son cycle. Une facture a été générée dans un état
draft. Elle inclut les postes de facturation en attente, y compris un prorata négatif, un prorata positif et le paiement complet pour le mois de février, dont le résultat est 125 EUR. Par défaut, la facture apparaît dans un étatdraftpendant environ une heure.Avancez l’horloge d’une heure afin de finaliser la facture.
Périodes d’essai
Tout d’abord, suivez les étapes ci-après pour commencer à utiliser des horloges de simulation :
- Créer une horloge de simulation
- Configurer votre simulation test
- Avancer l’horloge
- Surveiller et gérer les modifications
- Mettre la simulation à jour
Ensuite, vous pouvez commencer à tester les périodes d’essai avec les horloges de simulation. Imaginons que vous voulez que vos clients testent vos produits gratuitement pendant une période d’essai de sept jours avant de commencer à payer et vous souhaitez collecter les informations de paiement en amont. Suivez les étapes ci-après pour simuler cette situation en utilisant des horloges de simulation :
- Créez une nouvelle horloge de simulation et réglez son
frozen_timesur le 1er janvier. - Ajoutez un client et spécifiez son moyen de paiement. Dans ce cas, utilisez une carte de test.
- Créez un abonnement et ajoutez une période d’essai gratuit de sept jours :
- Suite à la création d’un abonnement avec une période d’essai gratuit de sept jours, un abonnement est créé dans un état
trialing. L’essai gratuit donne lieu à la génération d’une facture de 0 $. - Avancez la date au 5 janvier pour recevoir la notification d’événement customer.subscription.trial_will_end. Stripe envoie la notification trois jours avant la fin de la période d’essai. Vous pouvez utiliser cet événement webhook pour informer vos clients que la période d’essai arrive bientôt à son terme.
- Avancez la date au 8 janvier pour vérifier que l’abonnement est désormais à l’état
paidet qu’une facture de 50 EUR a été créée. - Avancez la date d’un cycle (par exemple, au 8 février pour un abonnement mensuel) pour constater le renouvellement.
Limitations
Pour un avancement efficace des horloges de test, Stripe limite la complexité de chaque simulation à :
- trois clients
- trois abonnements, y compris les abonnements planifiés, par client
- dix devis non associés à des clients
Mises en garde concernant le traitement des paiements
L’avancement de l’horloge de simulation ne prend pas encore en charge la collecte des paiements par prélèvement bancaire (comme les types de moyen de paiement us_bank_account). Stripe collecte les paiements après l’avancement de l’horloge de simulation. Pour tester les échecs de paiement :
Sélectionnez le paramètre Annuler l’abonnement après l’échec de toutes les relances de paiement.
Joignez un type de moyen de paiement
us_bank_accountà un client dont les paiements échouent.Créez un abonnement pour le client.
Faites avancer l’horloge de simulation pour collecter le paiement d’un abonnement.
Une fois l’horloge de simulation avancée, l’abonnement reste défini sur active. Cela signifie qu’aucune tentative d’encaissement du paiement n’a été effectuée durant l’avancement de l’horloge de simulation, et que l’abonnement n’est pas défini sur canceled en raison du motif payment_failed.
Écoutez l’événement invoice.payment_failed pour surveiller l’état d’abonnement retardé et le paiement de la facture. L’événement customer.subscription.deleted indique que l’état de l’abonnement est défini sur canceled.