There are typically two ways to run spectacles. The first is locally on your own machine to run tests as you develop LookML. The second is in a production continuous integration environment to automate the testing of any changes to your LookML project.
When doing LookML development, you can run spectacles to test your changes before you push them. To do so, we recommend running spectacles with your own Looker user credentials. If you are not an admin, you might need to ask one of your Looker admins to generate API keys for you.
There is one main benefit of running it with your local user. spectacles checks out the branch you specify as the user for which the credentials has been provided. If you use your own user’s credentials, spectacles can test any saved but uncommited changes that you have made. It will use the saved state of project that is visible in the Looker IDE.
When running spectacles in a continuous integration environment, we recommended using a dedicated Looker user. This allows you to limit permissions and avoid simultaneous access of Git branches from the Looker website and from the API.
If you set up spectacles in a CI environment with a user that is also used for LookML development, the usage of both simultaneously has the risk of conflicting. For example, if you were to check out a different branch via the web IDE half way through a CI run, the second half of the CI run would use the newly checked out branch and not the originally intended branch to test.
Pulling new changes as a CI user
When running spectacles in a CI pipeline using a dedicated CI user, you must provide the
--remote-reset flag. This instructs Looker to reset the branch’s current state to the remote version of the branch, which effectively pulls any new changes on the branch from the remote.
You shouldn’t use
--remote-reset in a local development workflow, because spectacles will reset the user’s local branch to remote, wiping any un-pushed or un-committed changes on the local branch. We are working with Looker on better ways to identify and warn when
--remote-reset would delete progress, but for now, you should only use the flag when running spectacles as a dedicated, non-developing CI user. A non-developing, CI user’s local branch should never be ahead of the remote branch.
Concurrency issues with spectacles in CI
When running spectacles in a CI environment, it is important you ensure that two runs on different branches do not occur simultaneously. spectacles checks out branch in question within the user’s workspace. If two runs using the same API user are executing simultaneously, they will use the same branch for the cross-over period.
For example, if spectacles is called to test branch
feature/first, it will change the user’s branch to
feature/firstand start running queries. If, while the first run is still happening, spectacles is called with the same user to test branch
feature/second, it will change the branch to
feature/second. As in the example above, both spectacles runs will then be using the second branch and the first run will not be testing the correct version of the codebase.