Document and refactor code around Cypress persisted state

[marktnoonan]

What would you like?

Working on PR #22755 I explored a bit around a mutation called setProjectPreferences (lately renamed to setProjectPreferencesInGlobalCache), which writes data to the /Application Support/Cypress/cy/{environment}/cache file. This file caches values for lastBrowser and testingType in objects that refer to each project by a simple string name, like PROJECT_PREFERENCES['frontend-shared']. Similar data in the projects folders state.json files is nested under more unique names with hashes (frontend-shared-b1d9d76cfc89097c4beaf3412d05b7e0). This makes sense since two projects called frontend-shared could be in different directories and by opened by Cypress.

The main purpose of that cache seems to be to maintain a USER object with email address, auth token, and name, and the PROJECTS which is a list of global mode project paths. The information stored under projects probably makes more sense to put in the project state.json with other similar data, to simplify how we are setting/getting data about projects. The folders are a better place to store project state since they are uniquely named.

In a recent conversation, @brian-mann explained the purpose of the cache file, and how its intended use is different from the project-level state.json and the projects/__global__/state.json. The usage has diverged from these original intentions, so we need a plan to bring things back into conformance, and some refactoring to make it easier to always choose the write one when writing new code that relies on values being persisted on user computers. Until we pick up that work, this issue will hold the documentation around the purposes of the three separate ways of storing state.

cache file

This is best thought of as "global state" that applies to Cypress generally, and to the Cypress user generally. Applies to all versions of Cypress and all projects.

Things that belong here

The USER object and COHORTS object are correctly recorded in this file. The name cache is hanging around for legacy reasons, but it should be thought of as a json file for this global state.

Things that don't belong here

Values in PROJECT_PREFERENCES should be in project level state.json with other project level state.

projects/__global__/state.json

This is state that applies to Cypress when it is operating in global mode.

Things that belong here

Launchpad position and size for global mode.

Things that don't belong here

"Global" values like majorVersionWelcomeDismissed should be in cache

projects/{projectName}-{id}/state.json

This is saved state for a particular project.

Things that belong here

specFilter is a good example of a truly project specific setting.

Things that don't belong here

There are things like app position and size, or navbar collapsed state, that are currently stored here but might make sense to move to cache based on whether they truly make sense as project-level settings.

How to resolve this

• determine "ideal place" for every value going forward - is the current behavior correct or should we change it?
• rename and refactor ideas of globalPreferences in the code to be more clear about "user/app settings", "global mode settings", "project settings"
• give Cypress the ability to rearrange the contents of these files when values are in the "wrong" place so that we can clean up existing saved state files. Lots to consider here, especially as regards backwards compat for people using multiple versions of Cypress. So not something to take lightly.