From 0cf091091768586edbc9fd6cd4eaa6c2f50b6238 Mon Sep 17 00:00:00 2001 From: JohannesDienst-askui Date: Wed, 6 Mar 2024 17:56:03 +0100 Subject: [PATCH] docs: instructions on how to setup dotenv environment (#DVRL-71) --- .../Installing AskUI/getting-started-linux.md | 32 +++++++++++++++++++ .../Installing AskUI/getting-started-macos.md | 32 +++++++++++++++++++ .../Installing AskUI/getting-started.md | 32 +++++++++++++++++++ .../write-your-first-instruction.md | 6 ++-- .../write-your-first-instruction.md | 6 ++-- .../write-your-first-instruction.md | 6 ++-- .../write-your-first-instruction.md | 6 ++-- 7 files changed, 108 insertions(+), 12 deletions(-) diff --git a/docs/docs/general/01-Getting Started/Installing AskUI/getting-started-linux.md b/docs/docs/general/01-Getting Started/Installing AskUI/getting-started-linux.md index 37627c00c..6cb2eb9ab 100644 --- a/docs/docs/general/01-Getting Started/Installing AskUI/getting-started-linux.md +++ b/docs/docs/general/01-Getting Started/Installing AskUI/getting-started-linux.md @@ -31,3 +31,35 @@ npx askui@latest init To create and serve a static HTML-Report you have to install [Allure](https://github.com/allure-framework/allure2#download) and then call `allure serve ./allure-results` from your root-directory. ::: + +## (Optional) Store Your Credentials in `.env`-File +Your credentials (_Access Token_ and _Workspace ID_) get stored in plain text in the file (`askui_example/helpers/askui-helper.ts`). Storing credentials in plain text increases their risk to be leaked by pushing them to a remote repository. + +To load them from the `.env` file that gets created you have to remove the `credentials` property from `UiControlClient` in `askui_example/helpers/askui-helper.ts` and activate the `dotenv`-environment by commenting in the import at the start of the same file: + +```typescript +aui = await UiControlClient.build({ + // Remove the credentials property to + // load credentials from .env file + credentials: { + workspaceId: '< your_workspace_id >', + token: '{{ your_access_token }}', + }, + reporter: new AskUIAllureStepReporter(), + }); +``` + +The resulting file looks like this: + +```typescript +... +import 'dotenv/config'; + +... + + aui = await UiControlClient.build({ + reporter: new AskUIAllureStepReporter(), + }); + +... +``` diff --git a/docs/docs/general/01-Getting Started/Installing AskUI/getting-started-macos.md b/docs/docs/general/01-Getting Started/Installing AskUI/getting-started-macos.md index 1b6e87b8b..1604f06d6 100644 --- a/docs/docs/general/01-Getting Started/Installing AskUI/getting-started-macos.md +++ b/docs/docs/general/01-Getting Started/Installing AskUI/getting-started-macos.md @@ -36,3 +36,35 @@ npx askui@latest init To create and serve a static HTML-Report you have to install [Allure](https://github.com/allure-framework/allure2#download) and then call `allure serve ./allure-results` from your root-directory. ::: + +## (Optional) Store Your Credentials in `.env`-File +Your credentials (_Access Token_ and _Workspace ID_) get stored in plain text in the file (`askui_example/helpers/askui-helper.ts`). Storing credentials in plain text increases their risk to be leaked by pushing them to a remote repository. + +To load them from the `.env` file that gets created you have to remove the `credentials` property from `UiControlClient` in `askui_example/helpers/askui-helper.ts` and activate the `dotenv`-environment by commenting in the import at the start of the same file: + +```typescript +aui = await UiControlClient.build({ + // Remove the credentials property to + // load credentials from .env file + credentials: { + workspaceId: '< your_workspace_id >', + token: '{{ your_access_token }}', + }, + reporter: new AskUIAllureStepReporter(), + }); +``` + +The resulting file looks like this: + +```typescript +... +import 'dotenv/config'; + +... + + aui = await UiControlClient.build({ + reporter: new AskUIAllureStepReporter(), + }); + +... +``` diff --git a/docs/docs/general/01-Getting Started/Installing AskUI/getting-started.md b/docs/docs/general/01-Getting Started/Installing AskUI/getting-started.md index 635ffba6e..99467eb9a 100644 --- a/docs/docs/general/01-Getting Started/Installing AskUI/getting-started.md +++ b/docs/docs/general/01-Getting Started/Installing AskUI/getting-started.md @@ -168,3 +168,35 @@ On the next page, you will dive deeper on how to write instructions in the AskUI ## Next Steps You are now ready to create your first workflow with AskUI! Please go to the next page [Write Your First Instruction](../write-your-first-instruction.md). + +## (Optional) Store Your Credentials in `.env`-File +Your credentials (_Access Token_ and _Workspace ID_) get stored in plain text in the file (`askui_example/helpers/askui-helper.ts`). Storing credentials in plain text increases their risk to be leaked by pushing them to a remote repository. + +To load them from the `.env` file that gets created you have to remove the `credentials` property from `UiControlClient` in `askui_example/helpers/askui-helper.ts` and activate the `dotenv`-environment by commenting in the import at the start of the same file: + +```typescript +aui = await UiControlClient.build({ + // Remove the credentials property to + // load credentials from .env file + credentials: { + workspaceId: '< your_workspace_id >', + token: '{{ your_access_token }}', + }, + reporter: new AskUIAllureStepReporter(), + }); +``` + +The resulting file looks like this: + +```typescript +... +import 'dotenv/config'; + +... + + aui = await UiControlClient.build({ + reporter: new AskUIAllureStepReporter(), + }); + +... +``` diff --git a/docs/docs/general/01-Getting Started/write-your-first-instruction.md b/docs/docs/general/01-Getting Started/write-your-first-instruction.md index 771af0f48..d861313e7 100644 --- a/docs/docs/general/01-Getting Started/write-your-first-instruction.md +++ b/docs/docs/general/01-Getting Started/write-your-first-instruction.md @@ -148,7 +148,7 @@ With AskUI, there are near-infinite ways to target an element. We outlined the t To close out the interactive annotation, use `CMD/CTRL + W` or `ESC`. #### Approach B: Filtering by Proximity: Using Relational Selectors -- **Process**: Chain multiple element descriptions together using commands like `leftOf()`, `above()`, etc., to create a unique selector based on element relationships. More information can be found in the [AskUI documentation](https://docs.askui.com/docs/0.11.6/general/Element%20Selection/relational-selectors). +- **Process**: Chain multiple element descriptions together using commands like `leftOf()`, `above()`, etc., to create a unique selector based on element relationships. More information can be found in the [AskUI documentation](../03-Element%20Selection/relational-selectors.md). - **Advantages**: Increases selector specificity, particularly useful in complex UIs with numerous similar elements. - **Best Used When**: Targeting elements in a densely populated UI or when elements lack unique identifiers. @@ -163,7 +163,7 @@ To close out the interactive annotation, use `CMD/CTRL + W` or `ESC`. ``` #### Approach C: Custom Element-Descriptions: Screenshot-Based Selection (Advanced) -- **Process**: Use a screenshot snippet of the desired element to locate its exact position on the screen. More information can be found in the [AskUI documentation](https://docs.askui.com/docs/0.11.6/general/Element%20Selection/text-and-element-selectors#custom-elements). +- **Process**: Use a screenshot snippet of the desired element to locate its exact position on the screen. More information can be found in the [AskUI documentation](../03-Element%20Selection/text-and-element-selectors.md#custom-elements). - **Advantages**: Highly accurate for unique or custom-designed elements. - **Best Used When**: The element has a distinct visual appearance. - **Considerations**: This method is sensitive to screen resolution changes; ensure consistency in the automation/testing environment. @@ -192,7 +192,7 @@ it('should click on my element', async () => { ### Step 3: Selecting the Right Action for Your Task In this step you translate your intention (e.g., click a button, enter text) into a programmable action. -To learn more about the different types of actions, check out our [API Documentation](https://docs.askui.com/docs/0.11.6/api/API/table-of-contents). +To learn more about the different types of actions, check out our [API Documentation](../../api/01-API/table-of-contents.md). In this case, we will use the `click` method, which is great for interacting with buttons, links and checkboxes. diff --git a/docs/versioned_docs/version-0.13.1/general/01-Getting Started/write-your-first-instruction.md b/docs/versioned_docs/version-0.13.1/general/01-Getting Started/write-your-first-instruction.md index 771af0f48..d861313e7 100644 --- a/docs/versioned_docs/version-0.13.1/general/01-Getting Started/write-your-first-instruction.md +++ b/docs/versioned_docs/version-0.13.1/general/01-Getting Started/write-your-first-instruction.md @@ -148,7 +148,7 @@ With AskUI, there are near-infinite ways to target an element. We outlined the t To close out the interactive annotation, use `CMD/CTRL + W` or `ESC`. #### Approach B: Filtering by Proximity: Using Relational Selectors -- **Process**: Chain multiple element descriptions together using commands like `leftOf()`, `above()`, etc., to create a unique selector based on element relationships. More information can be found in the [AskUI documentation](https://docs.askui.com/docs/0.11.6/general/Element%20Selection/relational-selectors). +- **Process**: Chain multiple element descriptions together using commands like `leftOf()`, `above()`, etc., to create a unique selector based on element relationships. More information can be found in the [AskUI documentation](../03-Element%20Selection/relational-selectors.md). - **Advantages**: Increases selector specificity, particularly useful in complex UIs with numerous similar elements. - **Best Used When**: Targeting elements in a densely populated UI or when elements lack unique identifiers. @@ -163,7 +163,7 @@ To close out the interactive annotation, use `CMD/CTRL + W` or `ESC`. ``` #### Approach C: Custom Element-Descriptions: Screenshot-Based Selection (Advanced) -- **Process**: Use a screenshot snippet of the desired element to locate its exact position on the screen. More information can be found in the [AskUI documentation](https://docs.askui.com/docs/0.11.6/general/Element%20Selection/text-and-element-selectors#custom-elements). +- **Process**: Use a screenshot snippet of the desired element to locate its exact position on the screen. More information can be found in the [AskUI documentation](../03-Element%20Selection/text-and-element-selectors.md#custom-elements). - **Advantages**: Highly accurate for unique or custom-designed elements. - **Best Used When**: The element has a distinct visual appearance. - **Considerations**: This method is sensitive to screen resolution changes; ensure consistency in the automation/testing environment. @@ -192,7 +192,7 @@ it('should click on my element', async () => { ### Step 3: Selecting the Right Action for Your Task In this step you translate your intention (e.g., click a button, enter text) into a programmable action. -To learn more about the different types of actions, check out our [API Documentation](https://docs.askui.com/docs/0.11.6/api/API/table-of-contents). +To learn more about the different types of actions, check out our [API Documentation](../../api/01-API/table-of-contents.md). In this case, we will use the `click` method, which is great for interacting with buttons, links and checkboxes. diff --git a/docs/versioned_docs/version-0.14.0/general/01-Getting Started/write-your-first-instruction.md b/docs/versioned_docs/version-0.14.0/general/01-Getting Started/write-your-first-instruction.md index 771af0f48..d861313e7 100644 --- a/docs/versioned_docs/version-0.14.0/general/01-Getting Started/write-your-first-instruction.md +++ b/docs/versioned_docs/version-0.14.0/general/01-Getting Started/write-your-first-instruction.md @@ -148,7 +148,7 @@ With AskUI, there are near-infinite ways to target an element. We outlined the t To close out the interactive annotation, use `CMD/CTRL + W` or `ESC`. #### Approach B: Filtering by Proximity: Using Relational Selectors -- **Process**: Chain multiple element descriptions together using commands like `leftOf()`, `above()`, etc., to create a unique selector based on element relationships. More information can be found in the [AskUI documentation](https://docs.askui.com/docs/0.11.6/general/Element%20Selection/relational-selectors). +- **Process**: Chain multiple element descriptions together using commands like `leftOf()`, `above()`, etc., to create a unique selector based on element relationships. More information can be found in the [AskUI documentation](../03-Element%20Selection/relational-selectors.md). - **Advantages**: Increases selector specificity, particularly useful in complex UIs with numerous similar elements. - **Best Used When**: Targeting elements in a densely populated UI or when elements lack unique identifiers. @@ -163,7 +163,7 @@ To close out the interactive annotation, use `CMD/CTRL + W` or `ESC`. ``` #### Approach C: Custom Element-Descriptions: Screenshot-Based Selection (Advanced) -- **Process**: Use a screenshot snippet of the desired element to locate its exact position on the screen. More information can be found in the [AskUI documentation](https://docs.askui.com/docs/0.11.6/general/Element%20Selection/text-and-element-selectors#custom-elements). +- **Process**: Use a screenshot snippet of the desired element to locate its exact position on the screen. More information can be found in the [AskUI documentation](../03-Element%20Selection/text-and-element-selectors.md#custom-elements). - **Advantages**: Highly accurate for unique or custom-designed elements. - **Best Used When**: The element has a distinct visual appearance. - **Considerations**: This method is sensitive to screen resolution changes; ensure consistency in the automation/testing environment. @@ -192,7 +192,7 @@ it('should click on my element', async () => { ### Step 3: Selecting the Right Action for Your Task In this step you translate your intention (e.g., click a button, enter text) into a programmable action. -To learn more about the different types of actions, check out our [API Documentation](https://docs.askui.com/docs/0.11.6/api/API/table-of-contents). +To learn more about the different types of actions, check out our [API Documentation](../../api/01-API/table-of-contents.md). In this case, we will use the `click` method, which is great for interacting with buttons, links and checkboxes. diff --git a/docs/versioned_docs/version-0.16.0/general/01-Getting Started/write-your-first-instruction.md b/docs/versioned_docs/version-0.16.0/general/01-Getting Started/write-your-first-instruction.md index 771af0f48..d861313e7 100644 --- a/docs/versioned_docs/version-0.16.0/general/01-Getting Started/write-your-first-instruction.md +++ b/docs/versioned_docs/version-0.16.0/general/01-Getting Started/write-your-first-instruction.md @@ -148,7 +148,7 @@ With AskUI, there are near-infinite ways to target an element. We outlined the t To close out the interactive annotation, use `CMD/CTRL + W` or `ESC`. #### Approach B: Filtering by Proximity: Using Relational Selectors -- **Process**: Chain multiple element descriptions together using commands like `leftOf()`, `above()`, etc., to create a unique selector based on element relationships. More information can be found in the [AskUI documentation](https://docs.askui.com/docs/0.11.6/general/Element%20Selection/relational-selectors). +- **Process**: Chain multiple element descriptions together using commands like `leftOf()`, `above()`, etc., to create a unique selector based on element relationships. More information can be found in the [AskUI documentation](../03-Element%20Selection/relational-selectors.md). - **Advantages**: Increases selector specificity, particularly useful in complex UIs with numerous similar elements. - **Best Used When**: Targeting elements in a densely populated UI or when elements lack unique identifiers. @@ -163,7 +163,7 @@ To close out the interactive annotation, use `CMD/CTRL + W` or `ESC`. ``` #### Approach C: Custom Element-Descriptions: Screenshot-Based Selection (Advanced) -- **Process**: Use a screenshot snippet of the desired element to locate its exact position on the screen. More information can be found in the [AskUI documentation](https://docs.askui.com/docs/0.11.6/general/Element%20Selection/text-and-element-selectors#custom-elements). +- **Process**: Use a screenshot snippet of the desired element to locate its exact position on the screen. More information can be found in the [AskUI documentation](../03-Element%20Selection/text-and-element-selectors.md#custom-elements). - **Advantages**: Highly accurate for unique or custom-designed elements. - **Best Used When**: The element has a distinct visual appearance. - **Considerations**: This method is sensitive to screen resolution changes; ensure consistency in the automation/testing environment. @@ -192,7 +192,7 @@ it('should click on my element', async () => { ### Step 3: Selecting the Right Action for Your Task In this step you translate your intention (e.g., click a button, enter text) into a programmable action. -To learn more about the different types of actions, check out our [API Documentation](https://docs.askui.com/docs/0.11.6/api/API/table-of-contents). +To learn more about the different types of actions, check out our [API Documentation](../../api/01-API/table-of-contents.md). In this case, we will use the `click` method, which is great for interacting with buttons, links and checkboxes.