Skip to content

Commit 309930c

Browse files
scytackiscytacki
committed
START-5 More detailed startup instructions
1 parent 973223e commit 309930c

File tree

1 file changed

+89
-37
lines changed

1 file changed

+89
-37
lines changed

‎README.md‎

Lines changed: 89 additions & 37 deletions
Original file line numberDiff line numberDiff line change
@@ -2,77 +2,129 @@
22

33
This is a bare-bones React project. It contains a simple React view with the libraries for using the [CODAP Plugin API](https://github.com/concord-consortium/codap/wiki/CODAP-Data-Interactive-Plugin-API).
44

5-
## Development
5+
# Copying from the starter project
66

7-
### Copying a starter project
7+
## Create a new repository
88

9+
There are two ways to create a new repository from this template:
10+
11+
### Method 1: Using GitHub Template Button
12+
1. Go to this repository's GitHub page
13+
2. Click the green "Use this template" button at the top
14+
3. Select "Create a new repository"
15+
4. Set your repository name (e.g. `new-repository`)
16+
5. Choose visibility (public/private)
17+
6. Click "Create repository from template"
18+
7. Clone your new repository:
19+
```
20+
git clone https://github.com/your-username/new-repository.git
21+
cd new-repository
22+
```
23+
24+
### Method 2: Using Command Line
925
1. Create a new public repository for your project (e.g. `new-repository`)
1026
2. Create a clone of the starter repo
1127
```
1228
git clone --single-branch https://github.com/concord-consortium/codap-plugin-starter-project.git new-repository
13-
```
14-
3. Update the starter repo
15-
16-
First, update and run the starter project:
17-
```
1829
cd new-repository
19-
npm install
20-
npm update
21-
npm start
22-
```
23-
The browser should automatically open [localhost:8080](http://localhost:8080) (or 8081 if you are already using 8080). Checking for the words "CODAP Starter Plugin".
24-
25-
It's ok if you see an error like `handleResponse: CODAP request timed out: [{"action":"update","resource":"interactiveFrame","values":{"name":"Sample Plugin","version":"0.0.1","dimensions":{"width":380,"height":680}}},{"action":"get","resource":"interactiveFrame"}]`. This just means that the plugin is running outside of Codap, so is not receiving responses to API requests, which is expected.
26-
27-
Also verify that the test suite still passes:
2830
```
29-
npm run test
30-
```
31-
32-
4. Next, re-initialize the repo to create a new history
31+
3. Next, re-initialize the repo to create a new history
3332
```
3433
rm -rf .git
3534
git init
3635
```
37-
5. Create an initial commit for your new project
36+
4. Add a remote to your GitHub repository
3837
```
39-
git add .
40-
git commit -m "Initial commit"
38+
git remote add origin https://github.com/concord-consortium/new-repository.git
4139
```
42-
6. Push to your new repository
40+
41+
## Initialize new repository
42+
43+
1. Run `npm install` to install dependencies
44+
2. Optionally Run: `npm update` to update the dependencies. If you can, it is best to do this in the `codap-plugin-starter-project` first before making your new repository.
45+
3. Run `npm start` to start the `webpack-dev-server` in development mode with hot module replacement
46+
4. Open [localhost:8080](http://localhost:8080) (or use port 8081 if you are already using 8080). You should see a basic plugin with a heading of "CODAP Starter Plugin".
47+
48+
It's ok if you see an error like `handleResponse: CODAP request timed out: [{"action":"update","resource":"interactiveFrame","values":{"name":"Sample Plugin","version":"0.0.1","dimensions":{"width":380,"height":680}}},{"action":"get","resource":"interactiveFrame"}]`. This just means that the plugin is running outside of Codap, so is not receiving responses to API requests, which is expected.
49+
5. Run `npm test` to verify that the test suite still passes.
50+
6. Run `npx playwright install` to install the playwright browsers
51+
7. Run `npm run test:playwright` to verify the playwright tests still pass. The Playwright tests verify that the plugin works correctly inside CODAP.
52+
8. Search and replace instances of `codap-plugin-starter-project` with `new-repository`.
53+
9. Search and replace instances of `CODAP Starter Plugin` and `CODAP Plugin Starter Project` with `New Plugin`.
54+
10. Update the general description of the project in the first section above.
55+
11. [Setup AWS keys for S3 Deployment](https://docs.google.com/document/d/1VqEwnHcmv5EnGq4fQI7l6zur_rV4F-BdKYEy4LdDjY4/edit?pli=1&tab=t.0). This is so the GitHub actions can deploy to S3 and save the Playwright results.
56+
12. Configure the Codecov token.
57+
1. Find the new repository at https://app.codecov.io/gh/concord-consortium
58+
2. Choose the repository token option
59+
3. Add the token to the GitHub repository as described on the codecov page.
60+
13. Remove this `Copying from the starter project` section of the `README`, but keep track of the next step.
61+
14. Create an initial commit for your new project and push it.
4362
```
44-
git remote add origin https://github.com/concord-consortium/new-repository.git
63+
git add .
64+
git commit -m "Initial commit"
4565
git push -u origin master
4666
```
47-
7. Open your new repository and update all instances of `codap-plugin-starter-project` to `new-repository`.
48-
Note: this will do some of the configuration for Travis deployment to S3, but you'll still need to follow
49-
the instructions [here](https://docs.google.com/document/d/e/2PACX-1vTpYjbGmUMxk_FswUmapK_RzVyEtm1WdnFcNByp9mqwHnp0nR_EzRUOiubuUCsGwzQgOnut_UiabYOM/pub).
50-
8. Your new repository is ready! Remove this section of the `README`, and follow the steps below to use it.
5167
52-
### Initial steps
68+
Your new repository is ready!
69+
70+
# Development
71+
72+
## Getting Started
73+
1. Clone this repository and `cd` into the new folder.
74+
2. Install the dependencies `npm install`.
75+
3. Run the development server `npm start`.
76+
4. Open [localhost:8080](http://localhost:8080) (or use port 8081 if you are already using 8080). You should see a basic plugin with a heading of "CODAP Starter Plugin".
77+
78+
It's ok if you see an error like `handleResponse: CODAP request timed out: [{"action":"update","resource":"interactiveFrame","values":{"name":"Sample Plugin","version":"0.0.1","dimensions":{"width":380,"height":680}}},{"action":"get","resource":"interactiveFrame"}]`. This just means that the plugin is running outside of Codap, so is not receiving responses to API requests, which is expected.
5379
54-
1. Clone this repo and `cd` into it
55-
2. Run `npm install` to pull dependencies
56-
3. Run `npm start` to run `webpack-dev-server` in development mode with hot module replacement
80+
## Testing
5781
58-
## Testing the plugin in CODAP
82+
### Jest Tests
83+
The project uses Jest for unit testing. To run the tests:
84+
```
85+
npm test
86+
```
87+
88+
### Playwright Tests
89+
The project uses Playwright for end-to-end testing. These tests verify that the plugin works correctly inside CODAP. Playwright has lots of features including a VSCode plugin. Below are some basic steps to get started.
90+
91+
Before running tests for the first time you need to install the Playwright browsers:
92+
```
93+
npx playwright install
94+
```
95+
96+
After this you can run the tests without showing a browser or run them with a visible browser.
97+
98+
#### Run without a visible browser
99+
```
100+
npm run test:playwright
101+
```
102+
If you want to view a test report of these tests you can run:
103+
```
104+
npx playwright show-report
105+
```
106+
#### Run showing the browser
107+
```
108+
npm run test:playwright:open
109+
```
110+
111+
### Testing in CODAP
59112
60113
There are two ways to test the plugin in CODAP:
61114
- running it locally on https and use the deployed CODAP
62115
- running it and CODAP locally on http
63116
64-
### HTTPS
117+
#### HTTPS
65118
1. Start the plugin with `npm run start:secure`. You need to first setup a local http certificate if you haven't done so: https://github.com/concord-consortium/codap/blob/main/v3/README.md#run-using-https
66119
2. Run CODAP v2 or v3 with the `di` parameter:
67120
- v2: https://codap.concord.org/app/?di=https://localhost:8080/
68121
- v3: https://codap3.concord.org/?di=https://localhost:8080/
69122
70-
### HTTP
123+
#### HTTP
71124
1. Start plugin webserver `npm start` (it will be on 8080 by default)
72125
2. Setup a local webserver running CODAP.
73126
- v2: Download the latest `build_[...].zip` file https://codap.concord.org/releases/zips/. Extract the zip to a folder and run it with a local webserver. For example `npx httpserver -p 8081`
74127
- v3: Checkout the v3 source, install the dependencies, and start the dev server: https://github.com/concord-consortium/codap/blob/main/v3/README.md#initial-steps. The dev server should automatically choose the next avaiable port which would normally be 8081
75128
3. Open CODAP with the plugin embedded in it: http://localhost:8081/static/dg/en/cert/index.html?di=http://localhost:8080
76129
77-
78130
For further information on [CODAP Data Interactive Plugin API](https://github.com/concord-consortium/codap/wiki/CODAP-Data-Interactive-Plugin-API).

0 commit comments

Comments
 (0)