Skip to content

Commit 407ecaf

Browse files
orchetectorchetect
committed
Updated README
1 parent 1c53b5a commit 407ecaf

1 file changed

Lines changed: 158 additions & 1 deletion

File tree

‎README.md‎

Lines changed: 158 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,160 @@
11
# xcode-simulator
22

3-
This action is intended to dynamically find the best available pre-installed Xcode device simulator for macOS images in GitHub Actions.
3+
This action is intended to dynamically find the best available pre-installed Xcode device simulator for macOS images in GitHub Actions.
4+
5+
## Motivation
6+
7+
Relevant Xcode device simulator names and platform versions are an ever-moving hamster wheel. In order to maintain GitHub Actions CI pipelines across dozens of open-source repositories, over the years I have gradually tweaked and refined scripts to aid in this process.
8+
9+
Over time, numerous quirks and edge cases of both GitHub actions runners and how Xcode behaves has led to a laundry list of steps involved in successfully preparing a device simulator for use on runners.
10+
11+
This acton is designed as a one-stop shop to select and prepare a device simulator, primarily with the intention of running unit tests on the simulator.
12+
13+
## Parameters
14+
15+
| Name | Required | Description | Format |
16+
| ---------------- | -------- | ------------------------------------------------------------ | ---------------------------- |
17+
| `refresh` | No | Refresh Xcode simulators by first calling the simulator controller to refresh by listing all local simulators. | `true` or `false` |
18+
| `download` | No | Asks the simulator controller to first download a relevant simulator for the platform specified by the target parameter. | `true` or `false` |
19+
| `workspace-path` | No | Relative path to the Xcode workspace. If the target is a Swift Package that exists in the root of the repository, omit this parameter. | Relative path from repo root |
20+
| `scheme` | Yes | Xcode scheme name that will be used when enumerating available device simulators. | String |
21+
| `target` | Yes | Target identifier (case-insensitive). See table below for full list of identifiers. | String |
22+
| `os-version` | No | Platform OS version (regular expression). | String |
23+
24+
Target identifiers supported, with tables listed in increasing degree of specificity:
25+
26+
| Target | Device Family | OS Version |
27+
| ------ | -------- | ------------------------------------------------------- |
28+
| `iOS` | Newest iPhone simulator | Newest OS version, unless specified |
29+
| `tvOS` | Newest Apple TV simulator | Newest OS version, unless specified |
30+
| `watchOS` | Newest Apple Watch simulator | Newest OS version, unless specified |
31+
| `visionOS` | Newest Vision Pro simulator | Newest OS version, unless specified |
32+
33+
| Target | Platform | Device Family | OS Version |
34+
| ------ | -------- | ------------------------------------------------------- | ------ |
35+
| `iphone` | iOS | Newest iPhone simulator | Newest OS version, unless specified |
36+
| `ipad` | iOS | Newest iPad simulator | Newest OS version, unless specified |
37+
| `tv` | tvOS | Newest Apple TV simulator | Newest OS version, unless specified |
38+
| `watch` | watchOS | Newest Apple Watch simulator | Newest OS version, unless specified |
39+
| `visionpro` | visionOS | Newest Vision Pro simulator | Newest OS version, unless specified |
40+
41+
| Target | Platform | Device Family | OS Version |
42+
| ------ | -------- | ------------------------------------------------------- | ------ |
43+
| `iphone-air` | iOS | Newest iPhone Air simulator | Newest OS version, unless specified |
44+
| `iphone-pro` | iOS | Newest iPhone Pro simulator | Newest OS version, unless specified |
45+
| `iphone-pro-max` | iOS | Newest iPhone Pro Max simulator | Newest OS version, unless specified |
46+
| `ipad-air` | iOS | Newest iPad Air simulator | Newest OS version, unless specified |
47+
| `ipad-mini` | iOS | Newest iPad mini simulator | Newest OS version, unless specified |
48+
| `ipad-pro` | iOS | Newest iPad Pro simulator | Newest OS version, unless specified |
49+
| `tv-4k` | tvOS | Newest Apple TV 4K simulator | Newest OS version, unless specified |
50+
| `watch-se` | watchOS | Newest Apple Watch SE simulator | Newest OS version, unless specified |
51+
| `watch-series` | watchOS | Newest Apple Watch Series simulator | Newest OS version, unless specified |
52+
53+
## Usage
54+
55+
Prepare an iOS device simulator (defaults to iPhone) using the latest device and operating system version in order to test a Swift Package:
56+
57+
```yaml
58+
jobs:
59+
build:
60+
runs-on: macos-latest
61+
steps:
62+
- uses: orchetect/xcode-simulator@main
63+
with:
64+
scheme: MySchemeName
65+
target: iOS
66+
```
67+
68+
Prepare an iOS device simulator (defaults to iPhone) using the latest device and operating system version in order to test an Xcode project named `MyProject.xcodeproj` located within the `MyProject` folder:
69+
70+
```yaml
71+
jobs:
72+
build:
73+
runs-on: macos-latest
74+
steps:
75+
- uses: orchetect/xcode-simulator@main
76+
with:
77+
workspace-path: MyProject/MyProject.xcodeproj/project.xcworkspace
78+
scheme: MySchemeName
79+
target: iOS
80+
```
81+
82+
Prepare an iOS device simulator using the latest iPhone Pro Max device running iOS 26.2:
83+
84+
```yaml
85+
jobs:
86+
build:
87+
runs-on: macos-latest
88+
steps:
89+
- uses: orchetect/xcode-simulator@main
90+
with:
91+
scheme: MySchemeName
92+
target: iphone-pro-max
93+
os-version: 26.2
94+
```
95+
96+
## Complete Examples
97+
98+
Prepare an iOS device simulator (defaults to iPhone) using the latest device and operating system version in order to test a Swift Package:
99+
100+
> [!TIP]
101+
>
102+
> Separating the build and test phases into separate steps is recommended for organization and clarity.
103+
>
104+
> Building (unlike testing) typically does not require a simulator destination and a generic destination can be supplied.
105+
106+
```yaml
107+
env:
108+
SCHEME: "MySchemeName"
109+
WORKSPACEPATH: ".swiftpm/xcode/package.xcworkspace" # Standard workspace location for Swift Package
110+
111+
jobs:
112+
build:
113+
runs-on: macos-latest
114+
steps:
115+
- uses: actions/checkout@main
116+
- name: Prepare Device Simulator
117+
id: prep-sim
118+
uses: orchetect/xcode-simulator@main
119+
with:
120+
refresh: true
121+
download: true
122+
scheme: ${{ env.SCHEME }}
123+
target: iOS
124+
- name: Build
125+
run: |
126+
xcodebuild build -workspace "$WORKSPACEPATH" \
127+
-scheme "$SCHEME" -destination "generic/platform=iOS"
128+
- name: Unit Test
129+
run: xcodebuild test -workspace "$WORKSPACEPATH" \
130+
-scheme "$SCHEME" -destination "platform=iOS Simulator,id=$DESTID"
131+
env:
132+
DESTID: ${{ steps.prep-sim.outputs.id }}
133+
```
134+
135+
## Documentation
136+
137+
This README serves as basic documentation.
138+
139+
## Roadmap
140+
141+
After a period of testing in various repositories, version 1 will be released.
142+
143+
## Author
144+
145+
Coded by a bunch of 🐹 hamsters in a trenchcoat that calls itself [@orchetect](https://github.com/orchetect).
146+
147+
## License
148+
149+
Licensed under the MIT license. See [LICENSE](https://github.com/orchetect/xcode-simulator/blob/master/LICENSE) for details.
150+
151+
## Community & Support
152+
153+
Please do not email maintainers for technical support. Several options are available for issues and questions:
154+
155+
- Questions and feature ideas can be posted to [Discussions](https://github.com/orchetect/xcode-simulator/discussions).
156+
- If an issue is a verifiable bug with reproducible steps it may be posted in [Issues](https://github.com/orchetect/xcode-simulator/issues).
157+
158+
## Contributions
159+
160+
Contributions are welcome. Posting in [Discussions](https://github.com/orchetect/xcode-simulator/discussions) first prior to new submitting PRs for features or modifications is encouraged.

0 commit comments

Comments
 (0)