Installing and testing your package

There are two ways to install your package: through the browser's user interface with clicks or through the SFDX CLI—a more automated experience. For this chapter, we will use the browser user interface to get a better impression of what your end users will see (assuming you permit them to do the install themselves). In the next section, the SFDX CLI path will be discussed.

When you created your package version earlier in this chapter, you should have received an email with a link to install the package. If not, take the 04t ID from your sfdx-project.json file and apply it to the end of the following URL:

https://login.salesforce.com/packaging/installPackage.apexp?p0=

Do not attempt to install your package in your project's current default scratch org where you developed the package. Instead, let's create a new scratch org for test purposes and open it to perform the install via the browser. Note that we are reusing the same scratch org configuration but you may want to have different configurations for testing:

sfdx force:org:create 
  --definitionfile project-scratch-def.json 
  --setalias test 
  --noancestors
  --nonamespace
sfdx force:org:open -u test

Here are some things to note about the preceding command line parameters:

• The --setalias parameter defines an alias for this org as "test"; conversely, we used "dev" for the alias for the scratch org used to develop the package. This now means that you can easily open either org directly by just using the alias, without having to remember any user name or password. Note that the -s / --setdefaultuser parameter is not used here so the "dev" scratch org remains the default for synchronization. 
• The --noancestors and --nonamespace parameters disable the standard behavior to have the scratch org inherit the namespace and ancestry behavior we discussed earlier. These are not needed to create scratch orgs for testing package installs.

Once the test scratch org opens, paste the preceding installation link into your browser. The installation process will start. A compact view of the initial installation page is shown in the following screenshot; click on the Continue button and follow the default installation prompts to complete the installation:

If your package has not gone through a Salesforce Security Review, as described earlier in this chapter, you will see a banner informing the user of this fact. This banner is also visible when users review installed packages under the Setup menu.

Package installation covers the following aspects (once the user has entered the package password, if one was set):

• Package overview: The platform provides an overview of the components that will be added or updated (if this is an upgrade) to the user. Note that, due to the namespace assigned to your package, these will not overwrite existing components in the subscriber org created by the subscriber.
• Connected App and Remote Access: If the package contains components that represent connections to the services outside of the Salesforce services, the user is prompted to approve these.
• Approve Package API Access: If the package contains components that make use of the client API (such as JavaScript code), the user is prompted to confirm and/or configure these. Such components will generally not be called much; features such as JavaScript Remoting are preferred, and they leverage the Apex runtime security configured post-installation.
• Security configuration: In this step, you can determine the initial visibility of the components being installed (objects, pages, and so on), selecting admin only or the ability to select the profiles to be updated. This option predates the introduction of permission sets, which permit post-installation configuration.

If you package profiles in your application, the user will need to remember to map these to the existing profiles in the subscriber org, as per step 2. This is a one-time option, as the profiles in the package are not actually installed, only merged. I recommend that you utilize permission sets to provide security configurations for your application. These are installed and are much more granular in nature.

When the installation is complete, navigate to the Installed Packages menu option under the Setup menu. Here, you can see confirmation of some of your package details, such as the namespace and version, as well as licensing details, which will be discussed later in this chapter.

It is also possible to provide a Configure link for your package, which will be displayed next to the package when installed and listed on the Installed Packages page in the subscriber org. Here, you can provide a Visualforce page to access configuration options and processes, for example. If you have enabled Seat based licensing, there will also be a Manage Licenses link to determine which users in the subscriber org have access to your package components, such as tabs, objects, and Visualforce pages. Licensing, in general, is discussed in more detail later in this chapter.

Automating package installation

It is possible to automate package installation using the Salesforce DX CLI. This can be useful if you want to automate the deployment of your packages to scratch orgs and/or other test orgs created as part of a Continuous Integration (CI) pipeline (as discussed in Chapter 13, Source Control and Continuous Integration). Run the following commands within the project directory (or VSCode Terminal pane).

The first command will first create a new scratch org, as described in the previous section; the next command will run the install command; and finally, the third command will open the test scratch org, where you can confirm via the Setup | Installed Packages menu item that the package has been installed:

sfdx force:org:create 
  --definitionfile project-scratch-def.json 
  --setalias test 
  --noancestors
  --nonamespace
sfdx force:package:install 
  --package "FormulaForce App@0.1.0-1" 
  --publishwait 10 
  --wait 10
  --targetusername test
sfdx force:org:open -u test

Note that the installation will also upgrade a package if the package is already installed. A few things to note about the preceding sfdx force:package:install parameters are as follows:

• The --publishwait parameter ensures that the command waits for any final background processing to complete before your package can be installed.
• The --package parameter uses the package alias defined in the sfdx-project.json file. This parameter can also take the 04t ID as well (this is useful if the command is not run within the project directory).
• The --targetusername parameter uses the test scratch org alias to explicitly define which scratch org to install the package in, since the creation of the scratch org (via the preceding command) did not overwrite the default scratch org.

The Salesforce DX CLI can also list packages installed in an org, for example, if you wanted to determine whether a dependent package needs to be installed or upgraded before running the preceding CLI. Finally, you can also uninstall packages if you wish.