It’s the last day of the sprint, and our poor QA tester is stuck. She has a story to test; it’s a seemingly complete and descriptive story; it uses the well-known format of “As a ___ I want to ___ so I can ___.” Armed with the story, our tester logs in as the given user … and promptly gets stuck.


After all, the developer read the story, fulfilled the requirements, and pushed the code. Why isn’t it working? It turns out the developer forgot to include some critical pieces of information in the delivered package.

How could this have been avoided? Let’s talk about a better way to define the user story, to ensure that important changes made as part of the user story are delivered correctly for testing and ultimately to production. I call these elements the 5 Ps of a testable story: Persona, Purpose, Pages, Profiles and Permission Sets.

Persona and Purpose

Persona and Purpose are the easiest to include correctly in a story. If you’re following agile methodology, your stories may already use the format of “As a ___ I want to ___ so I can ___.” That first blank gives you your Persona(s), while the last blank gives you the Purpose. As you’re writing the story or considering whether it’s complete, ask yourself whether there are additional Personas or Purposes that need to be considered, either in this story or in a new one.

For example, if the story lists a user that needs to create some information, is there another type of user that will need to consume that information? Perhaps they need read-only access to the data for reporting purposes. Failure to include proper visibility for related Personas can lead to test failures later or a need to create more user stories to close the gaps.

Even if your story accurately and completely defines a Persona and Purpose, it doesn’t guarantee that the final package will have all the missing pieces. Those missing pieces are Pages, Profiles, and Permission Sets.


Pages are the vehicle we use to show information to our user. If you’re in the Lightning user interface, Pages could mean one of two things: it could be the Page Layout, which defines the order, visibility, and editability of fields and related lists, or it could be a custom Lightning Page. These are our first 2 pitfalls for failing to deliver a fully testable story.

Let’s take the example of a story that requires the creation of a new custom object, and that this new object has lookups to Account and Contact. It’s not enough to simply describe the page layout of the new object. We also need to define the compact layout, which will, in turn, drive the heading of the Lightning page.

We also need to consider how that object will be rendered in other parts of Salesforce, such as on the Account and Contact pages. Do we need to add a new related list to each page? What fields need to be displayed on each related list? Depending on how you break out user stories, this information could be included in the original story or as a separate piece of functionality. And don’t forget that here, too, the object’s compact layout will affect what information is displayed when a user hovers over a related record.


Now that we’ve covered how page layouts will support our user story, we need to consider a closely related configuration — Profiles. Profiles control which page layouts and Lightning pages a user will see. This is one piece of metadata that is frequently missed when packaging a user story, and it leads to unnecessary failures in testing. Remember that simply defining a page layout or Lightning page might not be enough to make that new layout or Lightning page visible for your target users. The most frequent scenario where a Profile update is needed is when an object has multiple record types, and each record type has its own layout and/or Lightning page. In this situation, failing to push a Profile along with your page will lead to a testing failure.

Permission Sets are closely related to Profiles but are more flexible since they can be assigned to multiple users and roles, and they also lend themselves better to packaging in apps. Depending on your use case, you might choose to include object and field permissions in Permission Sets rather than Profiles. You could also include custom permissions in Permission Sets, and these can be used to further customize what a user sees on a Lightning Page. Whether you use Profiles or Permissions sets, you also need to consider whether you need to include permissions beyond simple object and field access.

If your story is more complex than just adding a custom object, and especially if the story involves custom code, carefully review your package to ensure you’re including proper access for Apex classes used by automations or custom components in any needed Profiles and Permission Sets. Carefully review any classes containing the @AuraEnabled or @InvocableMethod annotations — since this means these classes are used by custom components (@AuraEnabled) or Flows and Process Builder (@InvocableMethod).

And finally, don’t forget to also include access for any new Custom Metadata Types that your code depends on. Failing to include any of these in your Profile or Permission Set — or failing to deploy the items as part of your testable/deployable package, will lead to failures.

So the next time you get ready to mark a user story as being ready for QA, take some time to ensure that your deployment package includes all of the following elements:

  • Functionality that allows a Persona to accomplish a Purpose
  • Page Layouts and Lightning Pages that expose the functionality to your Persona
  • Profiles and Permission sets that define access to layouts, objects, fields, Apex classes, and custom metadata

Your QA team will thank you, and you will make their job just a little easier.

CodeScience enables businesses to thrive on the AppExchange. Having built 10% of the apps on the AppExchange, we bring partners the learnings from 300+ commercial applications. Contact us today!