# Spectacles

## Overview

This documentation provides a detailed guide on integrating Spectacles.dev with Paradime to enhance continuous integration (CI) workflows for your dbt project hosted on GitHub. 

This integration enables automated LookML testing and seamless deployment processes, ensuring high code quality and reliability. Spectacles runs a test suite, but instead of testing production data, it tests data in the [Turbo CI](https://docs.paradime.io/app-help/documentation/bolt/ci-cd#bolt-turbo-ci) schema that reflects the output of your dbt™️ changes.

<figure><img src="https://2337193041-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FHET0AD04uHMgdeLAjptq%2Fuploads%2FvE6rQD9PIiiPjkjKgswq%2FScreenshot%202024-07-28%20at%2021.59.31.png?alt=media&#x26;token=f0e1634a-1f64-4182-9fb1-a77859af62cc" alt=""><figcaption></figcaption></figure>

## Prerequisites

Before proceeding, ensure the following prerequisites are met:

* Active [**Spectacles.dev**](https://www.spectacles.dev/) account
* [**Spectacles.dev GitHub app installed**](https://docs.spectacles.dev/app/guides/integrating-with-github/) in your GitHub account with access to your dbt repository.
* [**Paradime GitHub app installed**](https://docs.paradime.io/app-help/documentation/integrations/ci-cd/github) in your GitHub account with access to your dbt repository.
* [**Paradime Scheduler connection**](https://docs.paradime.io/app-help/documentation/settings/connections/scheduler-environment) configured with target name: `ci`
* [**Paradime Bolt Turbo CI configured** ](https://docs.paradime.io/app-help/documentation/bolt/ci-cd/turbo-ci)in your Paradime workspace.

## Paradime Turbo CI configuration <a href="#dbt-cloud-requirements" id="dbt-cloud-requirements"></a>

* **Generates Full dbt Project Output:** The Turbo CI run must produce the complete output of your dbt project. If you are using the [modified state](https://docs.paradime.io/app-help/concepts/dbt-fundamentals/running-dbt/mastering-the-dbt-cli/methods#state-method) in your Turbo CI configuration, the initial step should clone your production schema into the target schema for each run See the example below:

{% code title="Turbo CI dbt commands" %}

```bash
dbt clone --target ci
dbt build --select state:modified+ --target ci
```

{% endcode %}

## LookML configuration <a href="#lookml-requirements" id="lookml-requirements"></a>

You will need to configure schema references in our LookML using a user attribute, allowing Spectacles to modify the `sql_table_name` in your views. This adjustment will direct Looker to query the Paradime Turbo CI-generated staging data instead of the production data.

[This guide](https://docs.spectacles.dev/app/guides/dbt/setting-up-user-attributes-dbt/) details the steps required to make these changes to your LookML.

## Spectacles configuration <a href="#lookml-requirements" id="lookml-requirements"></a>

### Set user attributes <a href="#set-user-attributes" id="set-user-attributes"></a>

For each user attribute you'd like to modify in Spectacles, you'll need to configure it with a default value on the Spectacles Settings page.

Here are the steps in Spectacles:

1. In the top-right, click **Settings ⚙️**.
2. Scroll down to the **Looker Settings** section.
3. Under **User attribute**, input the name of the user attribute that controls the schema in your LookML.
4. Under **Default value**, input the name of schema you use for production. For non-dbt Cloud runs, Spectacles will use this value.
5. Click **Update Settings**.

<figure><img src="https://2337193041-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FHET0AD04uHMgdeLAjptq%2Fuploads%2FZIBV3uEjzDy5PIOgYqv2%2FScreenshot%202024-07-28%20at%2012.38.02.png?alt=media&#x26;token=ffe9bc67-f21c-4545-a1b1-f5b95fc5ec3d" alt="" width="563"><figcaption></figcaption></figure>

{% hint style="info" %}
Want to know more about using user attributes with Spectacles? Find our guide to user attributes [here](https://docs.spectacles.dev/app/guides/using-user-attributes/).
{% endhint %}

### Set up a new Suite[​](https://docs.spectacles.dev/app/tutorials/dbt-cloud-integration/#set-up-a-new-suite) <a href="#set-up-a-new-suite" id="set-up-a-new-suite"></a>

Follow these steps to create a new Suite that triggers SQL validation whenever a pull request is opened and Paradime Turbo CI complete successfully.&#x20;

1. **Navigate to Suites**
   * In the top menu, click **Suites**.
   * Click **New Suite**.
2. **Create a Simple Suite**
   * Name your Suite: `Paradime PRs.`
3. **Configure Triggers**
   * Leave **all the options unchecked** as Paradime will trigger the Suite on completion of a Paradime Turbo CI.
   * In the **Schema User Attribute** field, select the user attribute created in Looker.
4. **Configure the SQL Validator**
   * **Explores to query**: Leave the default setting unless you need to specify models using the model selection syntax.
   * **Explores to exclude**: Leave the default setting.
   * **Fail fast**: Select **Yes**.
   * **Query concurrency**: Leave the default setting.
   * Uncheck **Is Enabled** for both the **Content Validator** and the **Assert Validator**.
5. **Finalize the Suite**
   * Click **Create Suite**.

Your new Suite is now set up to trigger SQL validation whenever a pull request is opened and Paradime Turbo CI completed successfully .

## Connect Spectacles.dev to your Paradime workspace <a href="#dbt-cloud-requirements" id="dbt-cloud-requirements"></a>

### What you need to configure the Spectacles integration?

1. **Get your Spectacles API key:** You can generate or replace your API key in the Settings page for your Spectacles organisation.

<figure><img src="https://2337193041-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FHET0AD04uHMgdeLAjptq%2Fuploads%2FOMnKwZlJhHju5UgcRe62%2FScreenshot%202024-07-28%20at%2013.46.38.png?alt=media&#x26;token=ee581886-cef7-49c8-8eba-3d97630de4ca" alt="" width="563"><figcaption></figcaption></figure>

{% hint style="warning" %}
Only one API key can be active at a time, so save your API key somewhere securely when generating it. If you lose it, you'll need to replace it with a new key.
{% endhint %}

2. To retrieve  the below information navigate to the suite you have created in the previews step that you want to trigger on the back of a Paradime Turbo CI run and copy the Url in you browser, it will look something like this:

`https://app.spectacles.dev/org/pN9xfJfvcH6crAG0lyl4/proj/tYEXxrhFnkDJWv9gidAI/suites/ppRIWcoQLkcf6B5Ay78d/update`

* **Get your Spectacles Org ID:** This will be the first ID after `org/` in your spectacles.dev url. In the above example, the org id is `pN9xfJfvcH6crAG0lyl4`.
* **Get your Spectacles Project ID:** This will be the second ID after `proj/` in your spectacles.dev url. In the above example, the projected id is `tYEXxrhFnkDJWv9gidAI`.
* **Get your Spectacles Suite ID**: This will be the third ID after `suites/` in your spectacles.dev url. In the above example, the Suite id is `ppRIWcoQLkcf6B5Ay78d`.

3. **Get the Looker** **Schema User Attribute** **name:** This has been [previously set in Looker](https://docs.spectacles.dev/app/guides/dbt/setting-up-user-attributes-dbt/) for your views in the `sql_table_name.` Based on the Spectacle.dev guide you might have called this `dbt_schema`.

<figure><img src="https://2337193041-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FHET0AD04uHMgdeLAjptq%2Fuploads%2FXBnYjihuHTsiQ9RgIbfJ%2FScreenshot%202024-07-28%20at%2013.52.11.png?alt=media&#x26;token=9409df00-7952-4fd2-b30f-bc7daee6a880" alt="" width="563"><figcaption></figcaption></figure>

3. **Get the Paradime scheduler connection schema value**: This value corresponds to the schema name field set in the connection used to execute Paradime Turbo CI.

<figure><img src="https://2337193041-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FHET0AD04uHMgdeLAjptq%2Fuploads%2Fo6OYhjDz2wedoLEKrOxh%2FScreenshot%202024-07-28%20at%2013.48.13.png?alt=media&#x26;token=c6290bcf-477d-4315-aaf6-72402144e996" alt="" width="563"><figcaption></figcaption></figure>

### Setup the Spectacles integration in your Paradime workspace

To finalize the Spectacles integration in Paradime, you need to configure a set of [Bolt Schedules Environment Variables](https://docs.paradime.io/app-help/documentation/settings/environment-variables/bolt-schedule-env-variables) within the Paradime Workspace.

<figure><img src="https://2337193041-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FHET0AD04uHMgdeLAjptq%2Fuploads%2F6KNPpIXdGLQSts2YF6KD%2FScreenshot%202024-07-28%20at%2022.04.16.png?alt=media&#x26;token=43926ebf-a8d4-453e-b8e4-30cd1c54b4db" alt="" width="563"><figcaption></figcaption></figure>

Use the predefined environment variable names as listed below:

| Environment Variable Name                   | Environment Variable Value example |
| ------------------------------------------- | ---------------------------------- |
| SPECTACLES\_API\_TOKEN                      | `eyJhbGci0Mwyjdb5srBdDsAVOKdN5E`   |
| SPECTACLES\_ORG\_ID                         | `pN9xfJfvcH6crAG0lyl4`             |
| SPECTACLES\_PROJECT\_ID                     | `tYEXxrhFnkDJWv9gidAI`             |
| SPECTACLES\_SUITE\_ID                       | `ppRIWcoQLkcf6B5Ay78d`             |
| SPECTACLES\_CI\_LOOKER\_SCHEMA\_NAME\_KEY   | `dbt_schema`                       |
| SPECTACLES\_CI\_LOOKER\_SCHEMA\_NAME\_VALUE | `ci`                               |

{% hint style="info" %}
For additional Looker User attributes, add more [Bolt Schedules Environment Variables](https://docs.paradime.io/app-help/documentation/settings/environment-variables/bolt-schedule-env-variables) as:\
`SPECTACLES_LOOKER_USER_ATTRIBUTE_<user_attribute_name> = <value>`
{% endhint %}