Difference between revisions of "Testing WHMCS"

From WHMCS Documentation

m (→‎Testing Modules)
(→‎Storage Settings and Test Environments)
 
(6 intermediate revisions by 3 users not shown)
Line 1: Line 1:
−
This page details how to test a WHMCS installation before going live, then resetting it ready for production use.  
+
We recommend that you follow the below steps to test your WHMCS installation and then reset it for production use before you make it available to your customers.  
  
 
==Testing Modules==
 
==Testing Modules==
−
WHMCS shipped registrar and gateway modules come with, where possible, a test mode or the ability to use a test environment that can be utilised to test transactions and domain orders. See our documentation for details on enabling test mode. For example, with the eNom registrar module, this is detailed here: https://docs.whmcs.com/Enom#Test_Mode
 
  
−
An example of enabling test mode in the eNom module can be seen here:
+
When possible, WHMCS-shipped registrar and gateway modules come with a test mode or the ability to use a test environment to test transactions and domain orders. For details on enabling test mode, see the relevant module's documentation (for example, [https://docs.whmcs.com/Enom#Test_Mode Enom's documentation]).
 +
 
 +
For example, enabling test mode in the eNom module resembles this example:
  
 
[[File:Enom-test-mode.png|800px]]
 
[[File:Enom-test-mode.png|800px]]
  
−
When testing provisioning modules, there is no test mode required. It is however advisable that all actions be reversed, as not only does this tidy things up, it tests that action as well. An example of this would be provisioning a cPanel account on a remote server, then using the '''Terminate''' module command button to remove it.
+
Testing provisioning modules does not require a test mode. However, make certain that you are able to reverse all of the actions that you perform, both to restore the system to its original state and to test more functionality. For example, you could provision a cPanel account on a remote server and then use the '''Terminate''' module command to remove it.
  
 
==Disabling Outgoing Emails==
 
==Disabling Outgoing Emails==
−
[[File:disable-emails.png|200px|thumb|right|Disable Email Toggle]] When testing, it is desirable in most cases (unless the test is specific to receiving emails) to prevent WHMCS from sending emails. To achieve this, navigate to '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > Mail tab''' and toggle the '''Disable Email Sending''' option to "On".
 
  
 
<div class="docs-alert-info">
 
<div class="docs-alert-info">
−
Disabling emails is a feature available in WHMCS 8.1 or above.  
+
We added this feature in WHMCS 8.1.
 
</div>
 
</div>
 +
 +
[[File:disable-emails.png|200px|thumb|right|Disable Email Toggle]] When testing, it is usually ideal to prevent WHMCS from sending emails (unless the test is specific to receiving emails).
 +
 +
To do this in WHMCS 8.1 and later:
 +
 +
# Go to the '''[[Mail Tab|Mail]]''' tab at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > General Settings'''.
 +
# Toggle '''Disable Email Sending''' to '''On'''.
  
 
==Placing Orders==
 
==Placing Orders==
−
Once you have configured your required modules in test mode, as detailed above, you will want to place test orders. To place test orders within the admin user interface, you will want to first create a client/account. Details on how to do this can be found in the [https://help.whmcs.com/m/installation/l/682009-manually-adding-a-client/ Manually Adding a Client] guide. It's also possible to add clients using the [https://developers.whmcs.com/api-reference/addclient AddClient] API for those with PHP experience. Ensure that the relevant domain or product pricing is configured before proceeding with testing orders. More information on that can be found here:
 
−
*[https://docs.whmcs.com/Domain_Pricing Domain Pricing]
 
−
*[https://docs.whmcs.com/Products_and_Services Products and Services]
 
−
[[File:Admin_order_form.png|200px|thumb|right|Admin Order Form]]
 
−
Orders can then be placed within the admin area; as an example, these steps would be used to place an order for a domain registration:
 
−
#On the Client Summary page, click the "Add New Order" link in the "Actions" panel.
 
−
#The system will preselect the client. Fill out the rest of the form, beginning with choosing the payment gateway you want their future invoices to use.
 
−
#Select None from the Product/Service menu.
 
−
#Select Monthly from the Billing Cycle menu for the product section.
 
−
#Enter the domain in the Domain textbox and select "Register" as the Domain Registration Option.
 
−
#Choose the number of years you want to invoice the client for at the time of renewal.
 
  
−
WHMCS will only ever trigger a registration request for a domain name when the invoice for it is paid.
+
After you configure your required modules in test mode, place some test orders.  
−
For products, please refer to the [https://docs.whmcs.com/Products_and_Services#Module_Settings Module Settings] to see how WHMCS handles this.
 
  
−
Orders can also be placed by using the [https://docs.whmcs.com/Clients:Summary_Tab#Login_as_Owner/ Login as Owner] function to see the workflow a customer would see.
+
To place test orders in the [[Admin Area]]:
 +
 
 +
# Create a client account using the process in [https://help.whmcs.com/m/installation/l/682009-manually-adding-a-client/ Manually Adding a Client].
 +
#* If you have PHP experience, you can also add clients using the <tt>[https://developers.whmcs.com/api-reference/addclient AddClient]</tt> API.
 +
#* Make certain to configure the relevant domain or product pricing before proceeding with testing orders. For more information, see [[Domain Pricing]] and [[Products and Services]].[[File:Admin_order_form.png|200px|thumb|right|Admin Order Form]]
 +
# Create multiple test orders. For example, to place an order for a domain registration:
 +
## In a client's profile's '''[[Clients:Summary Tab|Summary]]''' tab, click '''Add New Order''' in the "Actions" panel.
 +
## Fill out the displayed form, beginning with choosing the payment gateway you want the client's future invoices to use.
 +
## Select ''None'' from the '''Product/Service''' menu.
 +
## Select ''Monthly'' from the '''Billing Cycle''' menu for the product section.
 +
## Enter the domain for '''Domain''' and select "Register" for '''Domain Registration'''.
 +
## Choose the number of years you want to invoice the client for at the time of renewal.
 +
 
 +
You can also place an order by clicking '''Login as Owner''' in the client's profile's '''[[Clients:Summary Tab|Summary]]''' tab. This allows you to see the workflow a customer would see.
 +
 
 +
WHMCS will only ever trigger a registration request for a domain name when the client pays the invoice.
 +
For information about how WHMCS handles this for products, see [[Products_and_Services#Module_Settings|Module Settings]].
  
 
==Processing Transactions==
 
==Processing Transactions==
−
Once you have an invoice you wish to test payment on, you will want to do so according to the documentation for the gateway module(s) you are using. An example of a difference would be that PayPal Checkout requires you to login as a client/user and make payment from the client area by selecting the invoice itself, whereas Stripe would require a stored card/pay method for the invoice to be captured against. Please see [https://docs.whmcs.com/Pay_Methods Pay Methods] for more information.
+
 
 +
To test payment on an invoice, check our module documentation and follow the necessary process for the gateway module you are using.  
 +
 
 +
For example, [[PayPal Checkout]] requires you to log in as a client and pay from the Client Area by selecting the invoice itself, while Stripe requires you to capture payment against a stored card or pay method. For more information, see [[Pay Methods]].
  
 
==Checking Automation==
 
==Checking Automation==
 +
 
[[File:gateway_log_example.png|200px|thumb|right|Gateway Log]]  
 
[[File:gateway_log_example.png|200px|thumb|right|Gateway Log]]  
−
Once a payment has been processed against an invoice, the [https://docs.whmcs.com/Transactions#The_Gateway_Logs Gateway Log]  will detail it's result and any supporting data you require to validate success.
 
  
−
In respect of domain names and provisioning modules, the [https://docs.whmcs.com/Activity_Logs Activity Log] will record success or failure so you are aware of whether the expected automation actions have completed. The Activity Log will also record successful details from the payment applied to the invoice (such as the transaction being added).  
+
You can find details on payments that the system has processed against an invoice at '''Billing > [[Gateway Log]]'''. The log will list the results and other data to allow you to validate success.
  
−
Finally, should any errors occur with automation, the [https://docs.whmcs.com/Troubleshooting_Module_Problems Module Debug Log] will report the request sent and response received, allowing you to determine the issue and resolve it.
+
For domain registrars and provisioning modules, the '''Activity Log''' at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > [[System Logs]]''' or, prior to WHMCS 8.0, '''Utilities > Logs''' will record success or failure of the associated automation actions. This log also records details from the invoice's payment, like the addition of the transaction.
 +
 
 +
If automation encounters any errors, the '''[[Troubleshooting_Module_Problems|Module Debug Log]]''' will report the sent request and received response, allowing you to determine the issue and resolve it.
  
 
==Resetting Your Database==
 
==Resetting Your Database==
−
After you successfully install your billing system, run through a series of tests, including creating client accounts and placing test orders with your particular setup. Often, after you have finished your testing, you will no longer want any of these clients or orders in your system.  All you need to do is reset your system, which will remove all of your test accounts.
 
  
−
You can empty all the tables that contain clients' data by running the following SQL code on your database:  
+
After you successfully test your WHMCS configuration, you may want to reset it in order to remove the test accounts, orders, invoices, and other items that you created.
 +
 
 +
You can empty all of the tables that contain client data by running the following SQL code on your database:  
  
 
<div class="source-cli">
 
<div class="source-cli">
Line 89: Line 106:
 
<br/>TRUNCATE `tblticketreplies` ;
 
<br/>TRUNCATE `tblticketreplies` ;
 
<br/>TRUNCATE `tbltickets` ;
 
<br/>TRUNCATE `tbltickets` ;
 +
<br/>TRUNCATE `tbltodolist` ;
 +
<br/>TRUNCATE `tbltransaction_history` ;
 
<br/>TRUNCATE `tblupgrades` ;  
 
<br/>TRUNCATE `tblupgrades` ;  
 
<br/>TRUNCATE `tblusers`;
 
<br/>TRUNCATE `tblusers`;
Line 96: Line 115:
  
 
<div class="docs-alert-warning">
 
<div class="docs-alert-warning">
−
<span class="title">Note</span><br />
 
 
Resetting your database only deletes client accounts and information. You will not lose any configuration or product settings.
 
Resetting your database only deletes client accounts and information. You will not lose any configuration or product settings.
 
</div>
 
</div>
 +
 +
===Storage Settings and Test Environments===
 +
 +
When you use local storage locations and are switching between development (test) or live environments, it's important to update your storage settings. If the configured storage locations do not exist on your server, certain features (such as sending emails) may not function correctly.
 +
 +
<div class="docs-alert-warning">
 +
Amazon S3™ storage locations '''must''' have the required access credentials in order to function.
 +
</div>
 +
 +
For more information, see [[Migrating Between Storage Locations]].

Latest revision as of 14:25, 6 February 2023

We recommend that you follow the below steps to test your WHMCS installation and then reset it for production use before you make it available to your customers.

Testing Modules

When possible, WHMCS-shipped registrar and gateway modules come with a test mode or the ability to use a test environment to test transactions and domain orders. For details on enabling test mode, see the relevant module's documentation (for example, Enom's documentation).

For example, enabling test mode in the eNom module resembles this example:

Enom-test-mode.png

Testing provisioning modules does not require a test mode. However, make certain that you are able to reverse all of the actions that you perform, both to restore the system to its original state and to test more functionality. For example, you could provision a cPanel account on a remote server and then use the Terminate module command to remove it.

Disabling Outgoing Emails

We added this feature in WHMCS 8.1.

Disable Email Toggle
When testing, it is usually ideal to prevent WHMCS from sending emails (unless the test is specific to receiving emails).

To do this in WHMCS 8.1 and later:

  1. Go to the Mail tab at Configuration () > System Settings > General Settings.
  2. Toggle Disable Email Sending to On.

Placing Orders

After you configure your required modules in test mode, place some test orders.

To place test orders in the Admin Area:

  1. Create a client account using the process in Manually Adding a Client.
    • If you have PHP experience, you can also add clients using the AddClient API.
    • Make certain to configure the relevant domain or product pricing before proceeding with testing orders. For more information, see Domain Pricing and Products and Services.
      Admin Order Form
  2. Create multiple test orders. For example, to place an order for a domain registration:
    1. In a client's profile's Summary tab, click Add New Order in the "Actions" panel.
    2. Fill out the displayed form, beginning with choosing the payment gateway you want the client's future invoices to use.
    3. Select None from the Product/Service menu.
    4. Select Monthly from the Billing Cycle menu for the product section.
    5. Enter the domain for Domain and select "Register" for Domain Registration.
    6. Choose the number of years you want to invoice the client for at the time of renewal.

You can also place an order by clicking Login as Owner in the client's profile's Summary tab. This allows you to see the workflow a customer would see.

WHMCS will only ever trigger a registration request for a domain name when the client pays the invoice. For information about how WHMCS handles this for products, see Module Settings.

Processing Transactions

To test payment on an invoice, check our module documentation and follow the necessary process for the gateway module you are using.

For example, PayPal Checkout requires you to log in as a client and pay from the Client Area by selecting the invoice itself, while Stripe requires you to capture payment against a stored card or pay method. For more information, see Pay Methods.

Checking Automation

Gateway Log

You can find details on payments that the system has processed against an invoice at Billing > Gateway Log. The log will list the results and other data to allow you to validate success.

For domain registrars and provisioning modules, the Activity Log at Configuration () > System Logs or, prior to WHMCS 8.0, Utilities > Logs will record success or failure of the associated automation actions. This log also records details from the invoice's payment, like the addition of the transaction.

If automation encounters any errors, the Module Debug Log will report the sent request and received response, allowing you to determine the issue and resolve it.

Resetting Your Database

After you successfully test your WHMCS configuration, you may want to reset it in order to remove the test accounts, orders, invoices, and other items that you created.

You can empty all of the tables that contain client data by running the following SQL code on your database:

TRUNCATE `mod_invoicedata` ;
TRUNCATE `tblinvoicedata` ;
TRUNCATE `tblaccounts` ;
TRUNCATE `tblactivitylog` ;
TRUNCATE `tblaffiliates` ;
TRUNCATE `tblaffiliatesaccounts` ;
TRUNCATE `tblaffiliateshistory` ;
TRUNCATE `tblaffiliatespending` ;
TRUNCATE `tblaffiliateswithdrawals` ;
TRUNCATE `tblbankaccts`;
TRUNCATE `tblbillableitems` ;
TRUNCATE `tblcancelrequests` ;
TRUNCATE `tblclients` ;
TRUNCATE `tblclientsfiles` ;
TRUNCATE `tblcontacts` ;
TRUNCATE `tblcredit` ;
TRUNCATE `tblcreditcards`;
TRUNCATE `tblcustomfieldsvalues` ;
TRUNCATE `tbldomains` ;
TRUNCATE `tbldomainsadditionalfields` ;
TRUNCATE `tblemails` ;
TRUNCATE `tblhosting` ;
TRUNCATE `tblhostingaddons` ;
TRUNCATE `tblhostingconfigoptions` ;
TRUNCATE `tblinvoiceitems` ;
TRUNCATE `tblinvoices` ;
TRUNCATE `tblmodulequeue` ;
TRUNCATE `tblnotes` ;
TRUNCATE `tblorders` ;
TRUNCATE `tblpaymethods`;
TRUNCATE `tblquotes` ;
TRUNCATE `tblquoteitems` ;
TRUNCATE `tblsslorders` ;
TRUNCATE `tblticketlog` ;
TRUNCATE `tblticketnotes` ;
TRUNCATE `tblticketreplies` ;
TRUNCATE `tbltickets` ;
TRUNCATE `tbltodolist` ;
TRUNCATE `tbltransaction_history` ;
TRUNCATE `tblupgrades` ;
TRUNCATE `tblusers`;
TRUNCATE `tblusers_clients`;
TRUNCATE `tbluser_invites`;

Resetting your database only deletes client accounts and information. You will not lose any configuration or product settings.

Storage Settings and Test Environments

When you use local storage locations and are switching between development (test) or live environments, it's important to update your storage settings. If the configured storage locations do not exist on your server, certain features (such as sending emails) may not function correctly.

Amazon S3™ storage locations must have the required access credentials in order to function.

For more information, see Migrating Between Storage Locations.

Retrieved from "http://3.17.75.209/index.php?title=Testing_WHMCS&oldid=33871"