Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Docs #1009

Merged
merged 3 commits into from
Aug 8, 2019
Merged

Docs #1009

Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
149 changes: 149 additions & 0 deletions docs/contributing.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,149 @@
# Contributing

Universal Dashboard is comprised of PowerShell, C# and JavaScript. This document is intended to provide the details necessary to configure your environment and develop features and fix bugs in the Universal Dashboard repository.

## Configuring your Environment

You will need the following installed on your machine.

- [.NET Core v2.2 SDK](https://dotnet.microsoft.com/download)
- [Visual Studio](https://visualstudio.microsoft.com/free-developer-offers/) or [Visual Studio Code](https://code.visualstudio.com/)
- [NodeJS](https://nodejs.org/en/)
- [Firefox](https://www.mozilla.org/en-US/firefox/new/) - For integration tests

## Executing the Build

You can execute the build using the [build.ps1](https://github.com/ironmansoftware/universal-dashboard/blob/master/src/build.ps1) in the `src` folder.

By the default, the build will execute in the Debug configuration. If you are producing a build for development purposes, this configuration is what you will want to use. If you are producing a build for release purposes, use the Release configuration.

```
.\build.ps1 -Configuration Release
```

When building the module, PlatyPS is used to generate the MAML help files from markdown. This is a time consuming process due to performance issues with the PlatyPS module. You can avoid building the hep with the `-NoHelp` switch.

```
.\build.ps1 -NoHelp
```

The output from the build will be staged into the `.\src\output`.

### Executing the Build in VS Code

To execute the build in VS Code, you can use the 'Build Debug' and 'Build Release' tasks.

## Running Tests

The test suite is primarily comprised of Selenium tests written using the Selenium PowerShell module and Pester. You will need to have Firefox installed to execute the test suite. The test suite is divided into several different sections.

### Running the Core tests

The core tests can be found in the [src\UniversalDashboard.UITest](https://github.com/ironmansoftware/universal-dashboard/tree/master/src/UniversalDashboard.UITest) folder.

To run the entire test suite, execute the `shebang.tests.ps1` with the `-Integration` switch.

`.\src\UniversalDashboard.UITest\shebang.tests.ps1 -Integration`

### Running the Materialize Tests

The Materialize tests execute tests against the Materialize components. You can run the Materialize tests in release and debug modes. In debug mode, you can run the webpack dev server to allow for live updates to the code. Your browser will refresh when you make changes.

To run the tests, execute the `driver.ps1` file in the [Materialize tests folder](https://github.com/ironmansoftware/universal-dashboard/tree/master/src/UniversalDashboard.Materialize/Tests).

To run in release mode, use the `-Release` switch.

```
.\src\UniversalDashboard.Materialize\Tests\driver.ps1 -Release
```

To run in debug mode, first start the webpack-dev-server and the execute the driver without the release flag. Any changes you make in the Materialize folder will cause webpack to rebuild the JSX files and reload the browser. This is the fastest way to develop controls for Materialize.

You will need to start a new terminal to run the webpack-dev-server because it will block the console.

_First Terminal_

```
cd .\src\UniversalDashboard.Materialize
npm run dev
```

_Second Terminal_

```
.\src\UniversalDashboard.Materialize\Tests\driver.ps1
```

You can run tests for a single component by using the `-Control` parameter. Just provide the name of the control you'd like to run tests for.

```
.\src\UniversalDashboard.Materialize\Tests\driver.ps1 -Control fab
```

To output an Nunit XML file with the test results, use the `-OutputTestResultXml`.

```
.\src\UniversalDashboard.Materialize\Tests\driver.ps1 -OutputTestResultXml
```

### Running the tests in VS Code

To run the tests in VS Code, you can first run the 'Run Materialize Webpack Server' command and then run the 'Run Materialize Test' command. The `Run Materialize Test` command will ask for the name of the control you'd like to run.

### Running the Material UI Tests

The MaterialUI tests execute tests against the MaterialUI components. You can run the MaterialUI tests in release and debug modes. In debug mode, you can run the webpack dev server to allow for live updates to the code. Your browser will refresh when you make changes.

To run the tests, execute the `driver.ps1` file in the [MaterialUI tests folder](https://github.com/ironmansoftware/universal-dashboard/tree/master/src/UniversalDashboard.MaterialUI/Tests).

To run in release mode, use the `-Release` switch.

```
.\src\UniversalDashboard.MaterialUI\Tests\driver.ps1 -Release
```

To run in debug mode, first start the webpack-dev-server and the execute the driver without the release flag. Any changes you make in the MaterialUI folder will cause webpack to rebuild the JSX files and reload the browser. This is the fastest way to develop controls for MaterialUI.

You will need to start a new terminal to run the webpack-dev-server because it will block the console.

_First Terminal_

```
cd .\src\UniversalDashboard.MaterialUI
npm run dev
```

_Second Terminal_

```
.\src\UniversalDashboard.MaterialUI\Tests\driver.ps1
```

You can run tests for a single component by using the `-Control` parameter. Just provide the name of the control you'd like to run tests for.

```
.\src\UniversalDashboard.MaterialUI\Tests\driver.ps1 -Control fab
```

To output an Nunit XML file with the test results, use the `-OutputTestResultXml`.

```
.\src\UniversalDashboard.MaterialUI\Tests\driver.ps1 -OutputTestResultXml
```

## Debugging the Webserver

The webserver is written in C# and is started when you execute `Start-UDDashboard`. In order to debug the webserver you will need to attach Visual Studio or Visual Studio Code to an instance of powershell.exe or pwsh.exe that has or will load the UD module.

First, you should build the web server in debug.

```
.\src\build.ps1 -Configuration Debug -NoHelp
```

You can now create your test dashboard. This can either be part of a Pester test or simply a PS1 script that loads the module from the output directory. You may need to uninstall UniversalDashboard from your PSModulePath.

```
Import-Module C:\src\UniversalDashboard.Community\src\output\UniversalDashboard.Community.psd1
Start-UDDashboard -Port 1000
```
67 changes: 67 additions & 0 deletions docs/working-on-a-component.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,67 @@
# Working on a Component

This document is intended to help you add a feature or fix a bug in a component.

## Step 1: Build Universal Dashboard

Run the build script in VS Code using the 'Build Debug' task or by running the build script manually.

```
.\src\build.ps1 -Configuration Debug -NoHelp
```

You won't have to do this every time you want to edit a component.

## Step 2: Start the Materialize Webpack Dev Server

You can start the Materialize Webpack Dev Server by running the 'Start Materialize Webpack Dev Server' task in VS Code or by running npm directly.

```
cd .\src\UniversalDashboard.Materialize
npm run dev
```

## Step 3: Modify the component

The component code is in the `Components` folder and the PowerShell script is in the `Scripts` folder for the components.

```
cd .\src\UniversalDashboard.Materialize\Components
cd .\src\UniversalDashboard.Materialize\Scripts
```

## Step 4: Validate the Component

You should write a test case that reproduces the bug or uses the new feature in the `.\src\UniversalDashboard.Materialize\Tests` folder. Once you have the test stubbed out, you can then run the test.

An example test stub would look like this.

```
Context "Floating" {
Set-TestDashboard {
New-UDButton -Text "Click Me" -Id "button" -Floating
}

It "is floating" {

}
}
```

When you run the test, the browser will open and the button will quickly be shown. If you wish to leave the browser open so that you can work on your test or component, use `Wait-Debugger` to pause the test.

```
Context "Floating" {
Set-TestDashboard {
New-UDButton -Text "Click Me" -Id "button" -Floating
}

It "is floating" {
Wait-Debugger
}
}
```

You can now edit the JSX file for the component and the webpack dev server will automatically recompile the component.

If you edit the PowerShell script, you will have to restart your test script.
6 changes: 6 additions & 0 deletions src/.vscode/launch.json
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,12 @@
// For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
"version": "0.2.0",
"configurations": [
{
"name": ".NET Core Attach",
"type": "coreclr",
"request": "attach",
"processId": "${command:pickProcess}"
},
{
"name": "PowerShell Launch Current File",
"type": "PowerShell",
Expand Down
53 changes: 53 additions & 0 deletions src/.vscode/tasks.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,53 @@
{
// See https://go.microsoft.com/fwlink/?LinkId=733558
// for the documentation about the tasks.json format
"version": "2.0.0",
"tasks": [
{
"label": "Build Debug",
"command": "./build.ps1",
"args": ["-Configuration", "Debug", "-NoHelp"],
"group": "build",
"presentation": {
"reveal": "always",
"panel": "new"
}
},
{
"label": "Build Release",
"command": "./build.ps1",
"args": ["-Configuration", "Release"],
"group": "build",
"presentation": {
"reveal": "always",
"panel": "new"
}
},
{
"label": "Run Materialize Webpack Server",
"command": "./UniversalDashboard.Materialize/run-webpack.ps1",
"group": "build",
"presentation": {
"reveal": "always",
"panel": "new"
}
},
{
"label": "Run Materialize Test",
"command": "./UniversalDashboard.Materialize/Tests/driver.ps1",
"args": ["-Control", "${input:control}"],
"group": "test",
"presentation": {
"reveal": "always",
"panel": "new"
}
}
],
"inputs": [
{
"type": "promptString",
"id": "control",
"description": "Name of the control."
}
]
}
2 changes: 2 additions & 0 deletions src/UniversalDashboard.Materialize/run-webpack.ps1
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
Set-Location $PSScriptRoot
npm run dev